API overview

Unleash provides a set of APIs to give you full programmatic control over your feature flags and to connect your applications and services to Unleash. The main Unleash APIs are designed for SDK connections, frontend evaluation, and administration. Unleash Edge also exposes API-compatible endpoints for low-latency feature flag access.

Client API

The Client API is designed for backend services and returns complete flag configurations with all activation strategies for server-side evaluation.

Authentication: Backend tokens.

Key endpoints:

Backend tokens can be scoped to specific projects and environments. Create them at Admin settings > Access control > API access.

Frontend API

The Frontend API is designed for client-side environments and returns only enabled flags for a specific Unleash Context, providing security and performance benefits.

Authentication: Frontend tokens.

Key endpoints:

Frontend vs Client API

Each Frontend API request requires an Unleash Context for flag evaluation:

1
{
2
  "userId": "user-123",
3
  "properties": {
4
    "region": "us-east",
5
    "plan": "premium"
6
  }
7
}

Admin API

The Admin API provides comprehensive programmatic access to all Unleash resources. This API powers the Unleash Admin UI and enables automation workflows.

All requests require the Authorization header:

$
curl -H "Authorization: YOUR_TOKEN" \
>
  https://your-unleash-instance.com/api/admin/projects

Unleash Edge API

Unleash Edge sits between your applications and your Unleash instance, exposing endpoints that are compatible with the Client API and Frontend API. SDKs connect to Edge instead of connecting directly to Unleash, which reduces latency and offloads traffic from your main instance.

Edge serves cached Client API data for server-side evaluation and returns evaluated Frontend API responses for client-side applications.

Authentication: Backend tokens for Client API endpoints, frontend tokens for Frontend API endpoints.

Base paths:

• Client API endpoints: <your-edge-url>/api/client
• Frontend API endpoints: <your-edge-url>/api/frontend

API authentication and tokens

All Unleash APIs require authentication using an API token. The type of token you use depends on the API you are accessing and your specific use case.

Token types

Unleash supports four types of API tokens:

• Backend tokens: Used to connect backend SDKs and Unleash Edge to the Client API. Can be scoped to a specific project and environment. Must remain secret.
• Frontend tokens: Used to connect frontend SDKs to the Frontend API or Unleash Edge. These tokens are designed to be publicly accessible and have limited permissions. Can be scoped to a specific project and environment.
• Personal access tokens: Tied to a specific user account. Useful for testing, debugging, or providing temporary access to tools and scripts that need to interact with the Admin API.
• Service account tokens: The recommended method for providing API access to integrations, automation tools, and other non-human users. Service accounts provide a more secure and manageable way to grant Admin API access.

For an end-to-end Unleash integration, you might need to use multiple token types. For example, when connecting a frontend SDK to Unleash using Unleash Edge, you’ll need:

• A frontend token for the frontend SDK to securely communicate with Unleash Edge.
• A backend token for Unleash Edge to communicate with the main Unleash server.

Ensure that the backend token has access to the same project and environment (or a broader scope) as the frontend token.

Create an API token

Depending on your permissions, you can create API tokens in the Unleash Admin UI:

• Admin settings > Access control > API access: for backend or frontend tokens; requires the Admin root role, or a custom root role with API token permissions.
• Admin settings > Service accounts > New service account: for creating a service account and assigning a token.
• Settings > API access [inside a project]: for project-specific client or frontend tokens; permitted for project Members or users with a corresponding root role.
• Profile > View profile settings > Personal API tokens: for personal access tokens.

Learn more about API tokens and client keys.

API specification

For a comprehensive and interactive reference of all available endpoints, Unleash provides an OpenAPI specification. This is useful for exploring the APIs, generating client libraries, and for testing.

You can access the specification from your Unleash instance at the following paths:

• Interactive Swagger UI: /docs/openapi/
• Raw JSON specification: /docs/openapi.json

For detailed guides on each API, please refer to the full reference documentation.