API keys

API keys provide stateless authentication for server-to-server communication, automated scripts, and environments where browser-based sessions are not practical. Keys are scoped to a user and can optionally restrict which resources and actions are permitted.

API keys are issued by your provisioned API at its /token endpoint. The console does not manage keys directly.

Creating a key

Send a POST request to the /token endpoint on your provisioned API with the user's credentials and optional permissions.

{
  "email": "[email protected]",
  "password": "your-password",
  "permissions": {
    "posts": { "read": ["id", "title", "body"], "create": ["title", "body"] },
    "comments": { "read": ["id", "text"] }
  }
}

The response includes the full API key (prefixed with sna_). This is the only time the key is returned in plain text. Snaapi stores a hashed version internally.

Key properties

Each API key has the following properties.

Property	Type	Description
id	uuid	Unique identifier
name	string	Human-readable label
prefix	string	First characters of the key (for identification)
start	string	First 6 to 10 characters for secret scanning
userId	string	Owner of the key
enabled	boolean	Whether the key is active
permissions	JSON	Scoped resource/action/field permissions
metadata	JSON	Custom metadata
expiresAt	datetime	Optional expiration timestamp
rateLimitEnabled	boolean	Whether rate limiting is active
rateLimitMax	number	Maximum requests per time window
rateLimitTimeWindow	number	Time window duration (milliseconds)
refillInterval	number	How often the request bucket refills
refillAmount	number	Number of requests restored per refill
requestCount	number	Total requests made with this key
remaining	number	Requests remaining in the current window
lastRequest	datetime	Timestamp of the most recent request

Permissions structure

The KeyPermissionsSchema maps resource names to actions and their allowed fields. Permissions are a JSON object where each top-level key is a resource name. Under each resource, you list the allowed actions, and under each action, an array of the fields that the key can access.

{
  "posts": {
    "read": ["id", "title", "body"],
    "create": ["title", "body"]
  },
  "users": {
    "read": ["id", "email"]
  }
}

When a key has scoped permissions, they are intersected with the user's role permissions at request time. The effective permission is the narrower of the two. The key can never grant more access than the role allows.

If no permissions are specified, the key inherits the full permissions of the user's role.

Rate limiting

Rate limiting is enabled by default for API keys. The global default is configured per API. Per-key overrides are set via the key's rateLimitMax, rateLimitTimeWindow, refillInterval, and refillAmount properties.

When a key exceeds its rate limit, subsequent requests receive a 429 Too Many Requests response until the window resets or refills.

Examples

Create an API key

curl -X POST https://your-api.snaapi.cloud/token \
  -H "Content-Type: application/json" \
  -d '{
    "email": "[email protected]",
    "password": "your-password"
  }'

The response contains the full key (shown only once).

{
  "key": "sna_abc123def456..."
}

Use an API key to read data

curl https://your-api.snaapi.cloud/posts \
  -H "Authorization: Bearer sna_abc123def456..."

Create an API key with scoped permissions

To restrict a key so it can only read posts and create comments:

curl -X POST https://your-api.snaapi.cloud/token \
  -H "Content-Type: application/json" \
  -d '{
    "email": "[email protected]",
    "password": "your-password",
    "permissions": {
      "posts": { "read": ["id", "title", "body"] },
      "comments": { "create": ["post_id", "text"] }
    }
  }'

The key returned will only be able to perform the actions listed above, even if the user's role grants broader access.