Skip to main content
This guide walks you through the full setup flow: creating an account, configuring a project and environment, and evaluating your first feature flag from your application.
1

Register a user

Create your account with a name, email address, and password. Registration automatically creates an initial organization and assigns you as its owner.
curl -X POST http://localhost:8080/api/v1/register \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Onur Kacmaz",
    "username": "[email protected]",
    "password": "mypassword123"
  }'
Response:
{
  "user": {
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "name": "Onur Kacmaz",
    "email": "[email protected]",
    "role": "admin",
    "email_verified_at": null,
    "created_at": "2024-03-15T10:00:00Z",
    "updated_at": "2024-03-15T10:00:00Z"
  }
}
An initial organization is created automatically on registration. You do not need to call POST /api/v1/organizations unless you want to create additional organizations later.
2

Log in and capture your token

Authenticate with your credentials to receive a JWT access token and refresh token. The access token is scoped to your current organization.
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": null,
    "created_at": "2024-03-15T10:00:00Z",
    "updated_at": "2024-03-15T10:00:00Z"
  },
  "current_organization": {
    "id": "org-uuid-here",
    "slug": "onur-kacmaz",
    "name": "Onur Kacmaz",
    "role": "owner"
  },
  "organizations": [
    {
      "id": "org-uuid-here",
      "slug": "onur-kacmaz",
      "name": "Onur Kacmaz",
      "role": "owner"
    }
  ]
}
Save the token value — you will use it as a bearer token in all subsequent management requests.
TOKEN="eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
The access token expires after 1 hour. Use the refresh_token with POST /api/v1/refresh-token to get a new one. See Authentication for details.
3

Create a project

Projects are the workspace layer between your organization and its environments. Create one to group your flags and environments.
curl -X POST http://localhost:8080/api/v1/projects \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "My Project",
    "description": "Main product feature flags"
  }'
Response:
{
  "project": {
    "id": "proj-uuid-here",
    "organization_id": "org-uuid-here",
    "slug": "my-project",
    "name": "My Project",
    "description": "Main product feature flags",
    "created_at": "2024-03-15T10:01:00Z",
    "updated_at": "2024-03-15T10:01:00Z"
  }
}
Save the project.id as your PROJECT_ID.
PROJECT_ID="proj-uuid-here"
4

Create an environment

Environments represent deployment stages such as production or staging. Flags and API keys are scoped to a specific environment. The current region is automatically assigned to the new environment.
curl -X POST http://localhost:8080/api/v1/projects/$PROJECT_ID/environments \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "key": "production",
    "name": "Production",
    "description": "Production environment"
  }'
Response:
{
  "environment": {
    "id": "env-uuid-here",
    "project_id": "proj-uuid-here",
    "key": "production",
    "name": "Production",
    "description": "Production environment",
    "created_at": "2024-03-15T10:02:00Z",
    "updated_at": "2024-03-15T10:02:00Z"
  }
}
Save the environment.id as your ENV_ID.
ENV_ID="env-uuid-here"
5

Create an API key

API keys are environment-scoped machine credentials used to evaluate flags from your application. Create a server scoped key for backend evaluation.
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_ID'",
    "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 value is returned only once at creation time. Copy it now and store it securely — you cannot retrieve it again. If you lose it, rotate the key using POST /api/v1/projects/{project_id}/api-keys/{id}/rotate.
Save the secret for use in evaluation requests.
API_KEY="tgl_srv_abc123xyz..."
The three available scopes are:
ScopeUse case
serverServer-side flag evaluation
sdkClient SDK flag evaluation
streamSSE real-time flag change stream
6

Create a feature flag

Flags are the core resource in Togul. Each flag belongs to a specific environment and can be toggled independently. The salt used for percentage rollout hashing is auto-generated.
curl -X POST http://localhost:8080/api/v1/projects/$PROJECT_ID/flags \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "environment_id": "'$ENV_ID'",
    "key": "new-dashboard",
    "name": "New Dashboard",
    "description": "Enables the redesigned dashboard UI",
    "enabled": true,
    "default_value": false
  }'
Response:
{
  "flag": {
    "id": "flag-uuid-here",
    "environment_id": "env-uuid-here",
    "key": "new-dashboard",
    "name": "New Dashboard",
    "description": "Enables the redesigned dashboard UI",
    "enabled": true,
    "default_value": false,
    "salt": "a8f3c2d1",
    "created_at": "2024-03-15T10:04:00Z",
    "updated_at": "2024-03-15T10:04:00Z"
  }
}
The default_value is returned when the flag is disabled or no rules match the evaluation context.
7

Evaluate the flag

Call POST /api/v1/evaluate from your application using the X-API-Key header with your environment API key. Pass a context object with any attributes you want to use for targeting rules.
curl -X POST http://localhost:8080/api/v1/evaluate \
  -H "X-API-Key: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "flag_key": "new-dashboard",
    "environment_key": "production",
    "context": {
      "user_id": "user-123",
      "country": "TR",
      "plan": "premium"
    }
  }'
Response:
{
  "flag_key": "new-dashboard",
  "enabled": true,
  "value": false,
  "reason": "default"
}
The reason field tells you why that value was returned:
ReasonMeaning
disabledThe flag is turned off — default_value is returned
rule_matchAn active rule matched the context
defaultThe flag is enabled but no rules matched — default_value is returned
To return true for specific users, add a targeting rule with POST /api/v1/projects/{project_id}/rules. See the flag evaluation guide and percentage rollouts guide for examples.

​
Next steps

Authentication

Learn how to refresh tokens and switch organization context

Flag evaluation

Understand evaluation order and how to add targeting rules

Percentage rollouts

Roll out features to a percentage of users deterministically

Real-time streaming

Subscribe to live flag changes via Server-Sent Events

Build docs developers (and LLMs) love

Get started for freeTalk to us