API Tokens

API tokens provide a simple way to authenticate server-to-server requests without going through the OAuth2 flow. They are ideal for backend services, scripts, and automations.

API Tokens vs. OAuth2

Creating an API Token

Via the Web Console

1. Go to the stemp Console and navigate to Settings → API Keys.
2. Click Create API Key.
3. Enter a descriptive name (e.g., "POS Integration", "Sync Service").
4. Select the scopes your token needs.
5. Optionally set an expiration date.
6. Click Create.

Important: The full token is displayed only once. Copy and store it securely — you won't be able to see it again.

Via the API

curl -X POST https://api.stemp.app/api/v1/api-keys \
  -H "Authorization: Bearer <your_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "POS Integration",
    "scopes": ["pass:read", "pass:create", "loyalty:manage"],
    "expiresAt": "2026-12-31T23:59:59Z"
  }'

Response:

{
  "token": "sk_live_abc123...",
  "apiToken": {
    "id": "akt_abc123",
    "object": "api_token",
    "name": "POS Integration",
    "prefix": "sk_live_abc1",
    "scopes": ["pass:read", "pass:create", "loyalty:manage"],
    "expiresAt": "2026-12-31T23:59:59Z",
    "lastUsedAt": null,
    "createdAt": "2026-01-15T10:30:00Z",
    "createdByEmail": "you@example.com"
  }
}

Using an API Token

Include the token in the Authorization header:

curl -X GET https://api.stemp.app/api/v1/users \
  -H "Authorization: Bearer sk_live_abc123..."

Listing Tokens

curl -X GET https://api.stemp.app/api/v1/api-keys \
  -H "Authorization: Bearer <your_token>"

The response includes metadata about each token (name, prefix, scopes, last used) but never the full token value.

Revoking a Token

curl -X DELETE https://api.stemp.app/api/v1/api-keys/{tokenId} \
  -H "Authorization: Bearer <your_token>"

Revocation is immediate. All requests using the revoked token will return 401 Unauthorized.

Scope Restrictions

• A token can only be granted scopes that the creating user has access to.
• The api_token:manage scope is required to create, list, and revoke API tokens.
• Some scopes are API-only (e.g., api_token:manage, app:manage) and cannot be used by OAuth apps.

Security Best Practices

• Name tokens descriptively so you can identify their purpose later.
• Use minimal scopes — only grant the permissions the token needs.
• Set expiration dates for tokens that are used temporarily.
• Rotate tokens regularly — delete old tokens and create new ones.
• Never commit tokens to version control or expose them in client-side code.
• Monitor usage — check lastUsedAt to identify unused tokens that should be revoked.