corbado

README

Corbado Go SDK

The Corbado Go SDK provides convenient access to the Corbado Backend API from applications written in the Go language.

⚠ The Corbado Go SDK is commonly referred to as a private client, specifically designed for usage within closed backend applications. This particular SDK should exclusively be utilized in such environments, as it is crucial to ensure that the API secret remains strictly confidential and is never shared.

🚀 Getting started | 🛠 Services | 📚 Advanced | 💬 Support & Feedback

🚀 Getting started

Requirements

• Go 1.18 or later

Installation

Use the following command to install the Corbado Go SDK:

go get github.com/corbado/corbado-go/v2

Usage

To create a Corbado Go SDK instance you need to provide your Project ID, API secret , Frontend API and Backend API URLs which can be found at the Developer Panel.

package main

import (
    "github.com/corbado/corbado-go"
)

func main() {
    config, err := corbado.NewConfig("<Project ID>", "<API secret>", "<Frontend API>", "<Backend API>")
    if err != nil {
        panic(err)
    }

    sdk, err := corbado.NewSDK(config)
    if err != nil {
        panic(err)
    }
}

Examples

A list of examples can be found in the examples directory. Integration tests are good examples as well.

🛠 Services

The Corbado Go SDK provides the following services:

• Sessions for managing sessions (examples)
• Users for managing users (examples)
• Identifiers for managing identifiers (examples)

To use a specific service, such as Users, invoke it as shown below:

user, err := sdk.Users().Get(context.Background(), "usr-12345679")
if err != nil {
    panic(err)
}

📚 Advanced

Error handling

The Corbado Go SDK uses Go standard error handling (error interface). If the Backend API returns a HTTP status code other than 200, the Corbado Go SDK returns a ServerError error (which implements the error interface):

package main

import (
    "context"
    "fmt"

    "github.com/corbado/corbado-go"
)

func main() {
    config, err := corbado.NewConfig("<Project ID>", "<API secret>", "<Frontend API>", "<Backend API>")
    if err != nil {
        panic(err)
    }

    sdk, err := corbado.NewSDK(config)
    if err != nil {
        panic(err)
    }

    // Try to get non-existing user with ID 'usr-123456789'
    user, err := sdk.Users().Get(context.Background(), "usr-123456789")
    if err != nil {
        if serverErr := corbado.AsServerError(err); serverErr != nil {
            // Show HTTP status code (400 in this case)
            fmt.Println(serverErr.HTTPStatusCode)

            // Show request ID (can be used in developer panel to look up the full request
            // and response, see https://app.corbado.com/app/logs/requests)
            fmt.Println(serverErr.RequestData.RequestID)

            // Show runtime of request in seconds (server side)
            fmt.Println(serverErr.Runtime)

            // Show validation error messages (server side validation in case of HTTP
            // status code 400 (Bad Request))
            fmt.Printf("%+v\n", serverErr.Validation)
        } else {
            // Handle other errors
            panic(err)
        }

        return
    }

    fmt.Println(user.userID)
}

💬 Support & Feedback

Report an issue

If you encounter any bugs or have suggestions, please open an issue.

Slack channel

Join our Slack channel to discuss questions or ideas with the Corbado team and other developers.

Email

You can also reach out to us via email at vincent.delitz@corbado.com.

Vulnerability reporting

Please report suspected security vulnerabilities in private to security@corbado.com. Please do NOT create publicly viewable issues for suspected security vulnerabilities.

Documentation

Index

• Constants
• func AsServerError(err error) *servererror.ServerError
• func AsValidationError(err error) *validationerror.ValidationError
• func IsServerError(err error) bool
• func IsValidationError(err error) bool
• func NewLoggingClientOption() api.ClientOption
• type Config
  • func NewConfig(projectID string, apiSecret string, frontendAPI string, backendAPI string) (*Config, error)
  • func NewConfigFromEnv() (*Config, error)
• type Impl
  • func NewSDK(config *Config) (*Impl, error)
  • func (i *Impl) Identifiers() identifier.Identifier
  • func (i *Impl) Sessions() session.Session
  • func (i *Impl) Users() user.User
• type SDK

Constants

const Version = "2.2.0"

Functions

func AsServerError

func AsServerError(err error) *servererror.ServerError

AsServerError casts given error into a ServerError, if possible

func AsValidationError

func AsValidationError(err error) *validationerror.ValidationError

AsValidationError casts given error into a ValidationError, if possible

func IsServerError

func IsServerError(err error) bool

IsServerError checks if given error is a ServerError

func IsValidationError

func IsValidationError(err error) bool

IsValidationError checks if given error is a ValidationError

func NewLoggingClientOption

func NewLoggingClientOption() api.ClientOption

NewLoggingClientOption enhances HTTP client to log requests/responses

Types

type Config

type Config struct {
	ProjectID   string
	APISecret   string
	FrontendAPI string
	BackendAPI  string
	CacheMaxAge time.Duration

	JWKSRefreshInterval  time.Duration
	JWKSRefreshRateLimit time.Duration
	JWKSRefreshTimeout   time.Duration

	HTTPClient         *http.Client
	ExtraClientOptions []api.ClientOption
}

func NewConfig

func NewConfig(projectID string, apiSecret string, frontendAPI string, backendAPI string) (*Config, error)

NewConfig returns new config with sane defaults

func NewConfigFromEnv

func NewConfigFromEnv() (*Config, error)

NewConfigFromEnv created new config be reading the following environment variables: CORBADO_PROJECT_ID, CORBADO_API_SECRET, CORBADO_FRONTEND_API and CORBADO_BACKEND_API

type Impl

type Impl struct {
	HTTPClient *http.Client
	// contains filtered or unexported fields
}

func NewSDK

func NewSDK(config *Config) (*Impl, error)

NewSDK returns new SDK

func (*Impl) Identifiers

func (i *Impl) Identifiers() identifier.Identifier

Identifiers returns identifiers client

func (*Impl) Sessions

func (i *Impl) Sessions() session.Session

Sessions returns sessions client

func (*Impl) Users

func (i *Impl) Users() user.User

Users returns users client

type SDK

type SDK interface {
	Sessions() session.Session
	Users() user.User
	Identifiers() identifier.Identifier
}