auth

package
v2.3.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Mar 2, 2026 License: MIT Imports: 8 Imported by: 0

Documentation

Overview

Package auth provides authentication strategies for the QuickBase API.

QuickBase supports four authentication methods:

  • User Token: Long-lived tokens for server-side applications
  • Temporary Token: Short-lived tokens received from browser clients
  • SSO Token: SAML-based tokens for enterprise SSO integration
  • Ticket: Username/password authentication with proper user attribution

User Token (Recommended for Server-Side)

User tokens are long-lived tokens that don't expire. Generate one at: https://YOUR-REALM.quickbase.com/db/main?a=UserTokens 

client, _ := quickbase.New("myrealm",
    quickbase.WithUserToken("b9f3pk_xxxx_xxxxxxxxxxxxxxx"),
)

Temporary Token (Browser-Initiated)

Temp tokens are short-lived (~5 min), table-scoped tokens. Go servers receive them from browser clients (e.g., Code Pages) that fetch tokens using the user's QuickBase session. The browser sends tokens via HTTP headers. 

tokens := map[string]string{
    "bqr1111": r.Header.Get("X-QB-Token-bqr1111"),
}
client, _ := quickbase.New("myrealm",
    quickbase.WithTempTokens(tokens),
)

SSO Token (SAML)

Exchange a SAML assertion for a QuickBase temp token. Requires SAML SSO configured on your realm. 

client, _ := quickbase.New("myrealm",
    quickbase.WithSSOTokenAuth(samlAssertion),
)

See: https://developer.quickbase.com/operation/exchangeSsoToken

Ticket Authentication (Username/Password)

Ticket auth uses the legacy XML API (API_Authenticate) to exchange credentials for an authentication ticket. Unlike user tokens, tickets properly attribute record changes (createdBy/modifiedBy) to the authenticated user. 

client, _ := quickbase.New("myrealm",
    quickbase.WithTicketAuth("user@example.com", "password"),
)

The XML API call: 

POST https://{realm}.quickbase.com/db/main
QUICKBASE-ACTION: API_Authenticate
Content-Type: application/xml

<qdbapi>
    <username>user@example.com</username>
    <password>secret</password>
    <hours>12</hours>
</qdbapi>

Returns a ticket valid for 12 hours (configurable up to ~6 months). The ticket is then used with REST API calls via the QB-TICKET authorization header.

See: https://help.quickbase.com/docs/api-authenticate

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

This section is empty.

Types

type ExistingTicketStrategy 

type ExistingTicketStrategy struct {
	// contains filtered or unexported fields
}

ExistingTicketStrategy authenticates using a pre-existing ticket.

Unlike TicketStrategy which obtains a ticket via API_Authenticate, this strategy uses a ticket that was already obtained elsewhere (e.g., by a browser client calling API_Authenticate directly).

This is useful for Code Page scenarios where:

  1. Browser calls API_Authenticate with user credentials
  2. Browser sends ticket to Go server
  3. Go server uses the ticket for REST API calls

The server never sees the user's credentials - only the ticket.

func NewExistingTicketStrategy 

func NewExistingTicketStrategy(ticket string) *ExistingTicketStrategy

NewExistingTicketStrategy creates a strategy using a pre-existing ticket.

Example: 

strategy := auth.NewExistingTicketStrategy(ticketFromBrowser)

func (*ExistingTicketStrategy) ApplyAuth 

func (s *ExistingTicketStrategy) ApplyAuth(req *http.Request, token string)

ApplyAuth applies the ticket to the Authorization header.

func (*ExistingTicketStrategy) GetToken 

func (s *ExistingTicketStrategy) GetToken(ctx context.Context, dbid string) (string, error)

GetToken returns the existing ticket.

func (*ExistingTicketStrategy) HandleAuthError 

func (s *ExistingTicketStrategy) HandleAuthError(ctx context.Context, statusCode int, dbid string, attempt int, maxAttempts int) (string, error)

HandleAuthError handles 401 errors. Since we don't have credentials, we cannot re-authenticate - the ticket has expired.

type SSOTokenOption 

type SSOTokenOption func(*SSOTokenStrategy)

SSOTokenOption configures an SSOTokenStrategy.

func WithSSOHTTPClient 

func WithSSOHTTPClient(client *http.Client) SSOTokenOption

WithSSOHTTPClient sets a custom HTTP client for token exchange.

type SSOTokenStrategy 

type SSOTokenStrategy struct {
	// contains filtered or unexported fields
}

SSOTokenStrategy authenticates using SAML SSO token exchange. This strategy exchanges a SAML assertion for a QuickBase temp token.

func NewSSOTokenStrategy 

func NewSSOTokenStrategy(samlToken, realm string, opts ...SSOTokenOption) *SSOTokenStrategy

NewSSOTokenStrategy creates a new SSO token authentication strategy.

func (*SSOTokenStrategy) ApplyAuth 

func (s *SSOTokenStrategy) ApplyAuth(req *http.Request, token string)

ApplyAuth applies the SSO-derived token to the Authorization header.

func (*SSOTokenStrategy) GetToken 

func (s *SSOTokenStrategy) GetToken(ctx context.Context, dbid string) (string, error)

GetToken returns the SSO-derived token, exchanging the SAML token if needed.

func (*SSOTokenStrategy) HandleAuthError 

func (s *SSOTokenStrategy) HandleAuthError(ctx context.Context, statusCode int, dbid string, attempt int, maxAttempts int) (string, error)

HandleAuthError handles 401 errors by refreshing the SSO token.

type SignOuter 

type SignOuter interface {
	// SignOut clears credentials from memory, preventing further API calls.
	// This does NOT invalidate tokens on QuickBase's servers.
	SignOut()
}

SignOuter is an optional interface for strategies that support signing out. Currently only TicketStrategy implements this interface.

type Strategy 

type Strategy interface {
	// GetToken returns the authentication token for the given table/app ID.
	// The dbid parameter is used for temp tokens which are scoped to specific tables.
	// For user tokens, dbid is ignored.
	GetToken(ctx context.Context, dbid string) (string, error)

	// ApplyAuth applies authentication headers to the request.
	// This typically sets the Authorization header with the token.
	ApplyAuth(req *http.Request, token string)

	// HandleAuthError handles authentication errors and potentially refreshes tokens.
	// Returns a new token if refresh was successful, empty string otherwise.
	// This is called when the API returns 401 Unauthorized.
	HandleAuthError(ctx context.Context, statusCode int, dbid string, attempt int, maxAttempts int) (string, error)
}

Strategy defines the interface for authentication strategies.

All authentication strategies must implement this interface. The SDK provides four built-in implementations:

type TempTokenOption 

type TempTokenOption func(*TempTokenStrategy)

TempTokenOption configures a TempTokenStrategy.

func WithInitialTempToken 

func WithInitialTempToken(token string) TempTokenOption

WithInitialTempToken sets an initial temp token received from a browser client.

Use this when you've received a single token and don't know the dbid yet. The token will be used for the first request and associated with that dbid.

For multiple tokens with known dbids, use WithTempTokens instead.

func WithInitialTempTokenForTable 

func WithInitialTempTokenForTable(token string, dbid string) TempTokenOption

WithInitialTempTokenForTable sets an initial temp token for a specific table.

func WithTempTokens 

func WithTempTokens(tokens map[string]string) TempTokenOption

WithTempTokens sets multiple temp tokens mapped by table ID.

This is the preferred way to initialize tokens when you know the dbids.

type TempTokenStrategy 

type TempTokenStrategy struct {
	// contains filtered or unexported fields
}

TempTokenStrategy authenticates using QuickBase temporary tokens.

Temp tokens are short-lived (~5 min), table-scoped tokens that verify a user is logged into QuickBase via their browser session.

Go servers receive temp tokens from browser clients (e.g., Code Pages) that fetch them using the user's QuickBase session. The browser sends tokens via HTTP headers (e.g., X-QB-Token-{dbid}).

Example: 

func handler(w http.ResponseWriter, r *http.Request) {
    tokens := map[string]string{
        "bqr1111": r.Header.Get("X-QB-Token-bqr1111"),
    }
    client, _ := quickbase.New("realm",
        quickbase.WithTempTokens(tokens),
    )
    // Use client...
}

func NewTempTokenStrategy 

func NewTempTokenStrategy(realm string, opts ...TempTokenOption) *TempTokenStrategy

NewTempTokenStrategy creates a new temporary token authentication strategy.

func (*TempTokenStrategy) ApplyAuth 

func (s *TempTokenStrategy) ApplyAuth(req *http.Request, token string)

ApplyAuth applies the temp token to the Authorization header.

func (*TempTokenStrategy) GetToken 

func (s *TempTokenStrategy) GetToken(ctx context.Context, dbid string) (string, error)

GetToken returns a temp token for the given table ID.

Since Go servers can't fetch temp tokens (no browser cookies), this returns a token that was set via WithInitialTempToken, WithTempTokens, or SetToken.

func (*TempTokenStrategy) HandleAuthError 

func (s *TempTokenStrategy) HandleAuthError(ctx context.Context, statusCode int, dbid string, attempt int, maxAttempts int) (string, error)

HandleAuthError handles 401 errors. For temp tokens, we can't refresh server-side (no browser cookies), so we just remove the invalid token.

func (*TempTokenStrategy) Invalidate 

func (s *TempTokenStrategy) Invalidate(dbid string)

Invalidate removes a token for a specific table.

func (*TempTokenStrategy) InvalidateAll 

func (s *TempTokenStrategy) InvalidateAll()

InvalidateAll removes all tokens.

func (*TempTokenStrategy) SetToken 

func (s *TempTokenStrategy) SetToken(dbid string, token string)

SetToken stores a temp token for a specific table ID.

Use this to add tokens received from the browser during the request lifecycle.

type TicketOption 

type TicketOption func(*TicketStrategy)

TicketOption configures a TicketStrategy.

func WithTicketHTTPClient 

func WithTicketHTTPClient(client *http.Client) TicketOption

WithTicketHTTPClient sets a custom HTTP client for authentication requests.

func WithTicketHours 

func WithTicketHours(hours int) TicketOption

WithTicketHours sets the ticket validity duration in hours. Default is 12 hours. Maximum is 4380 hours (~6 months).

type TicketStrategy 

type TicketStrategy struct {
	// contains filtered or unexported fields
}

TicketStrategy authenticates using API_Authenticate (XML API).

This strategy exchanges username/password credentials for an authentication ticket, which is then used with REST API calls. Unlike user tokens, tickets properly attribute record changes (createdBy/modifiedBy) to the authenticated user.

The ticket is obtained lazily on the first API call. The password is discarded after authentication and not stored. When the ticket expires (401 error), an AuthenticationError is returned and a new client must be created.

Tickets are valid for 12 hours by default, configurable up to ~6 months (4380 hours).

func NewTicketStrategy 

func NewTicketStrategy(username, password, realm string, opts ...TicketOption) *TicketStrategy

NewTicketStrategy creates a new ticket authentication strategy.

The username is typically the user's email address registered with QuickBase. The password is the user's QuickBase password.

Authentication is performed lazily on the first API call. After successful authentication, the password is discarded from memory.

Example: 

strategy := auth.NewTicketStrategy("user@example.com", "password", "myrealm")

With custom ticket validity: 

strategy := auth.NewTicketStrategy("user@example.com", "password", "myrealm",
    auth.WithTicketHours(24*7), // 1 week
)

func (*TicketStrategy) ApplyAuth 

func (s *TicketStrategy) ApplyAuth(req *http.Request, token string)

ApplyAuth applies the ticket to the Authorization header.

func (*TicketStrategy) GetToken 

func (s *TicketStrategy) GetToken(ctx context.Context, dbid string) (string, error)

GetToken returns the authentication ticket, calling API_Authenticate if needed.

func (*TicketStrategy) HandleAuthError 

func (s *TicketStrategy) HandleAuthError(ctx context.Context, statusCode int, dbid string, attempt int, maxAttempts int) (string, error)

HandleAuthError handles 401 errors. Since the password is discarded after initial authentication, this returns an empty string to signal that re-authentication is not possible and the user must create a new client.

func (*TicketStrategy) SignOut 

func (s *TicketStrategy) SignOut()

SignOut clears the stored ticket from memory, preventing further API calls.

This does NOT invalidate the ticket on QuickBase's servers - tickets remain valid until they expire. However, this client will no longer be able to make API calls after SignOut is called.

To make API calls again, create a new client with fresh credentials.

Use this when:

  • A user logs out of your application
  • You want to force re-authentication
  • You're done with a session and want to clear credentials from memory

Example: 

// User clicks "logout"
client.SignOut()
// Next API call will fail with "signed out" error

func (*TicketStrategy) UserID 

func (s *TicketStrategy) UserID() string

UserID returns the authenticated user's ID (available after first API call).

type UserTokenStrategy 

type UserTokenStrategy struct {
	// contains filtered or unexported fields
}

UserTokenStrategy authenticates using a QuickBase user token.

User tokens are long-lived tokens that don't expire and work across all apps the user has access to. This is the simplest and most common authentication method.

Generate a user token at: https://YOUR-REALM.quickbase.com/db/main?a=UserTokens

func NewUserTokenStrategy 

func NewUserTokenStrategy(token string) *UserTokenStrategy

NewUserTokenStrategy creates a new user token authentication strategy.

Example: 

strategy := auth.NewUserTokenStrategy("b9f3pk_xxx_xxxxxxxxxxxxxx")

func (*UserTokenStrategy) ApplyAuth 

func (s *UserTokenStrategy) ApplyAuth(req *http.Request, token string)

ApplyAuth applies the user token to the Authorization header.

func (*UserTokenStrategy) GetToken 

func (s *UserTokenStrategy) GetToken(ctx context.Context, dbid string) (string, error)

GetToken returns the user token (ignores dbid since user tokens are global).

func (*UserTokenStrategy) HandleAuthError 

func (s *UserTokenStrategy) HandleAuthError(ctx context.Context, statusCode int, dbid string, attempt int, maxAttempts int) (string, error)

HandleAuthError handles 401 errors by returning the same token for retry. User tokens can't be refreshed, so we just retry with the same token.

func (*UserTokenStrategy) XMLAuthElement 

func (s *UserTokenStrategy) XMLAuthElement(token string) (string, string)

XMLAuthElement returns the XML element for user token authentication. The XML API requires tokens as body elements, not headers. See: https://help.quickbase.com/docs/api-getdbpage

type XMLAuthProvider 

type XMLAuthProvider interface {
	// XMLAuthElement returns the XML element name and token value for XML API auth.
	// For user tokens, returns ("usertoken", "token-value").
	// For tickets, returns ("ticket", "ticket-value").
	XMLAuthElement(token string) (elementName string, elementValue string)
}

XMLAuthProvider is an optional interface for strategies that support XML API authentication. The XML API uses different authentication than the JSON API - tokens must be included in the request body as XML elements, not in HTTP headers.

Strategies that implement this interface will have their tokens injected into XML request bodies automatically when using the xml sub-package.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.