Authentication

Togul separates authentication into two distinct mechanisms depending on what you are doing:

Bearer tokens — Used for management operations: creating flags, managing members, configuring environments, and other admin tasks. Obtained by logging in.
API keys — Used by your application servers and SDKs to evaluate feature flags. Scoped to a specific environment.

Bearer tokens
API keys

Bearer tokens

Bearer tokens are JWT access tokens scoped to your current organization membership and permission set. You obtain them by logging in.

Obtaining a token

curl -X POST http://localhost:8080/api/v1/login \
  -H "Content-Type: application/json" \
  -d '{
    "username": "[email protected]",
    "password": "mypassword123"
  }'

Response:

{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "refresh_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "user": {
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "name": "Onur Kacmaz",
    "email": "[email protected]",
    "role": "admin",
    "email_verified_at": "2024-03-15T10:00:00Z",
    "created_at": "2024-03-15T10:00:00Z",
    "updated_at": "2024-03-15T10:00:00Z"
  },
  "current_organization": {
    "id": "org-uuid-here",
    "slug": "acme-corp",
    "name": "Acme Corp",
    "role": "owner"
  },
  "organizations": [
    {
      "id": "org-uuid-here",
      "slug": "acme-corp",
      "name": "Acme Corp",
      "role": "owner"
    }
  ]
}

The response contains:

token — JWT access token with a 1-hour expiry. Use this in the Authorization header for all management requests.
refresh_token — JWT refresh token with a 30-day expiry. Use this to obtain new access tokens without re-entering credentials.
current_organization — The organization context the token is scoped to, including your role in that organization.
organizations — All organizations you belong to. Use these IDs to switch context.

Using the token

Include the access token in the Authorization header as a Bearer token on every management request:

curl -X GET http://localhost:8080/api/v1/me \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."

Token expiry and scoping

Token	Expiry	Purpose
`token` (access token)	1 hour	Authenticate management API requests
`refresh_token`	30 days	Obtain new access tokens

Access tokens are scoped to a specific organization. If you belong to multiple organizations, each token is valid only for the organization it was issued for. Use organization switching to change context.

API keys

API keys are environment-scoped machine credentials used to evaluate feature flags from your application code. Unlike bearer tokens, they are not tied to a user session.

Creating an API key

API keys are created per project and scoped to a specific environment. Requires the api_keys.write permission.

curl -X POST http://localhost:8080/api/v1/projects/$PROJECT_ID/api-keys \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "environment_id": "env-uuid-here",
    "name": "Production server key",
    "scope": "server"
  }'

Response:

{
  "api_key": {
    "id": "key-uuid-here",
    "project_id": "proj-uuid-here",
    "environment_id": "env-uuid-here",
    "name": "Production server key",
    "scope": "server",
    "key_prefix": "tgl_srv_",
    "last_used_at": null,
    "last_used_ip": null,
    "expires_at": null,
    "revoked_at": null,
    "created_at": "2024-03-15T10:03:00Z",
    "updated_at": "2024-03-15T10:03:00Z"
  },
  "secret": "tgl_srv_abc123xyz..."
}

The secret is returned only once at creation time. Store it immediately in a secrets manager or environment variable. If you lose it, you must rotate the key.

API key scopes

Scope	Permitted operations
`server`	Evaluate flags via `POST /api/v1/evaluate`
`sdk`	Evaluate flags via `POST /api/v1/evaluate`
`stream`	Subscribe to real-time flag changes via `GET /api/v1/stream`

Use server for backend services. Use sdk for client-side SDKs. Use stream for applications that need live flag updates.

Using an API key

Pass the API key in the X-API-Key header:

curl -X POST http://localhost:8080/api/v1/evaluate \
  -H "X-API-Key: tgl_srv_abc123xyz..." \
  -H "Content-Type: application/json" \
  -d '{
    "flag_key": "new-dashboard",
    "environment_key": "production",
    "context": {
      "user_id": "user-123",
      "country": "TR"
    }
  }'

Token refresh

Access tokens expire after 1 hour. Use the refresh token to get a new access token without requiring the user to log in again. The refresh token is rotated on each use — the old refresh token is invalidated and a new one is returned.

curl -X POST http://localhost:8080/api/v1/refresh-token \
  -H "Content-Type: application/json" \
  -d '{
    "refresh_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
  }'

Response:

{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "refresh_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "user": {
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "name": "Onur Kacmaz",
    "email": "[email protected]",
    "role": "admin",
    "email_verified_at": "2024-03-15T10:00:00Z",
    "created_at": "2024-03-15T10:00:00Z",
    "updated_at": "2024-03-15T10:00:00Z"
  },
  "current_organization": {
    "id": "org-uuid-here",
    "slug": "acme-corp",
    "name": "Acme Corp",
    "role": "owner"
  },
  "organizations": [
    {
      "id": "org-uuid-here",
      "slug": "acme-corp",
      "name": "Acme Corp",
      "role": "owner"
    }
  ]
}

Always replace your stored refresh token with the new one returned in the response. The previous refresh token is immediately invalidated.

Organization switching

If you belong to multiple organizations, your access token is scoped to one organization at a time. To switch context, call POST /api/v1/me/switch-organization with your target organization ID and your current refresh token.

curl -X POST http://localhost:8080/api/v1/me/switch-organization \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "organization_id": "other-org-uuid-here",
    "refresh_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
  }'

Response:

{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "refresh_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "user": {
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "name": "Onur Kacmaz",
    "email": "[email protected]",
    "role": "admin",
    "email_verified_at": "2024-03-15T10:00:00Z",
    "created_at": "2024-03-15T10:00:00Z",
    "updated_at": "2024-03-15T10:00:00Z"
  },
  "current_organization": {
    "id": "other-org-uuid-here",
    "slug": "other-org",
    "name": "Other Org",
    "role": "developer"
  },
  "organizations": [
    {
      "id": "org-uuid-here",
      "slug": "acme-corp",
      "name": "Acme Corp",
      "role": "owner"
    },
    {
      "id": "other-org-uuid-here",
      "slug": "other-org",
      "name": "Other Org",
      "role": "developer"
    }
  ]
}

The returned token is now scoped to the new organization. The current_organization field reflects the switched context. The refresh token is rotated as part of this operation.

You must be a member of the target organization for the switch to succeed. A 403 Forbidden is returned if you are not.

Security best practices

Store tokens securely

Never store bearer tokens or API key secrets in source code, client-side JavaScript, or version control.
Use environment variables or a secrets manager (e.g., AWS Secrets Manager, HashiCorp Vault) to inject credentials at runtime.
For browser-based applications, avoid storing tokens in localStorage — prefer httpOnly cookies or in-memory storage.

Rotate API keys regularly

API keys do not expire by default. Rotate them periodically or after any suspected compromise using POST /api/v1/projects/{project_id}/api-keys/{id}/rotate. The old secret is immediately invalidated when rotated.You can also set an expires_at timestamp when creating or rotating a key to enforce automatic expiry.

Use minimum required scopes

When creating API keys, choose the narrowest scope that meets your use case:

Use server or sdk for flag evaluation — not stream unless you need real-time updates.
Never use a bearer token in application code that evaluates flags. Bearer tokens have broad management permissions and are not intended for machine-to-machine evaluation calls.

Handle token expiry gracefully

Access tokens expire after 1 hour. Build token refresh logic into your application:

Catch 401 Unauthorized responses.
Call POST /api/v1/refresh-token with your stored refresh token.
Update your stored tokens with the new access token and rotated refresh token.
Retry the original request.

If the refresh token has also expired (after 30 days), the user must log in again.

Revoke keys when no longer needed

When decommissioning a service or rotating credentials, revoke old API keys with DELETE /api/v1/projects/{project_id}/api-keys/{id}. This immediately invalidates the key and prevents further use.

Get Started

Core Concepts

Guides

Account & Billing

Bearer tokens

Obtaining a token

Using the token

Token expiry and scoping

API keys

Creating an API key

API key scopes

Using an API key

Token refresh

Organization switching

Security best practices

Build docs developers (and LLMs) love

Get Started

Core Concepts

Guides

Account & Billing

​Bearer tokens

​Obtaining a token

​Using the token

​Token expiry and scoping

​API keys

​Creating an API key

​API key scopes

​Using an API key

​Token refresh

​Organization switching

​Security best practices

Build docs developers (and LLMs) love

Bearer tokens

Obtaining a token

Using the token

Token expiry and scoping

API keys

Creating an API key

API key scopes

Using an API key

Token refresh

Organization switching

Security best practices