Skip to main content

Authentication & Usage Tokens

Gabber supports two different authentication schemes:

  • API Key Authentication
  • End-user ("Human") Usage Tokens

Many of Gabber's APIs can be accessed via your end-users directly or be tied to your end users. Gabber calls end-users "humans".

Humans are represented by a freeform identifier, typically a user id or an email, and are definied by you.

API Key Authentication​

API Key authentication is the standard method for server-side API use. API keys must be kept secret and should only be used server-side. You can find your API key on the dashboard

To use an API key, include it in the x-api-key header of your requests to the Gabber APIs. An optional x-human-id can added which ties the request to a human. For example, calling the Chat Completions Endpoint with an x-human-id would enforce the token count limits for them.

POST /some-endpoint HTTP/1.1
Host: api.gabber.dev
x-api-key: your_api_key_here
x-human-id: some_user_id_from_your_app

Usage Tokens​

Humans can also interact with Gabber APIs directly from your app using usage tokens. Instead of using an API key + a human id, you can create a usage token that represents that pairing of API key + human id to authenticate requests.

This makes it so you don't need to re-implement all of Gabber's endpoints in your backend.

For example, many of Gabber's LLM features are OpenAI-API compatible. It'd be annoying to have to implement another OpenAI-API compatible endpoint on your backend, just to proxy requests and responses to Gabber's endpoint.

With usage tokens, you can directly use an OpenAI SDK in your frontend application where the human acts on behalf of your Gabber API key with limits imposed.

┌───────────────────┐                                              
│ Your backend w/   │    2.Backend generates token w/ limits       
│ secret gabber key │      using POST/usage/token                  
│                  ─┼──────────────────────────────────────────┐   
│                   │                                          │   
│                   │                                          │   
│                  ◄┼───────────────────────────────┐          │   
│ ▲                 │    4.Your backend optionally  │          │   
└─┼─────────────────┘      responds to webhooks ┌───┼──────────▼──┐
  │                        from Gabber          │   │             │
  │1.Client asks                                │                 │
  │  for token                                  │ Gabber backend  │
  │                                             │                 │
  │                                             │                 │
┌─┼─────────────────┐                           │     ▲           │
│                   │                           └─────┼───────────┘
│Your client app    │                                 │            
│(Web, iOS, etc.)  ─┼─────────────────────────────────┘            
│                   │      3.Client uses token to interact         
│                   │        with Gabber APIs directly             
└───────────────────┘

Creating a Usage Token​

When creating a usage token, you no longer specify usage limits (like conversational_seconds). Instead, you configure a TTL (time to live) — how long the token should be valid.

If the TTL is exceeded, Gabber will automatically revoke the token. You can also revoke tokens manually or update their TTL during the session.

Tokens are still created with your API key using the /v1/usage/token endpoint.

You can revoke a token via the /v1/usage/token/revoke API and update the TTL via /v1/usage/token/update_ttl.

Managing Token Validity​

You can update or revoke tokens dynamically:

  • Update TTL:
    POST /v1/usage/token/update_ttl
    Payload: { "human": "<human_id>", "ttl_seconds": 3600 }

  • Revoke token manually:
    POST /v1/usage/token/revoke
    Payload: { "human": "<human_id>" }

  • Check token validity:
    POST /v1/usage/token/check
    Payload: { "human": "<human_id>" }