Token Management

API tokens authenticate your requests to the Geog API. This guide covers creating, managing, and securing your tokens.

Creating a Token

All organization members can create API tokens:

1. Go to Tokens in the console sidebar
2. Click Create Token
3. Enter a descriptive name (e.g., "Production", "Dev Server", "CI/CD Pipeline")
4. Select the scopes your token needs
5. Click Create
6. Copy the token immediately. It's only shown once.

Store your token securely. If you lose it, you'll need to create a new one.

Token Scopes

Scopes control what your token can access. Only grant the scopes your application needs:

Most applications only need tiles:read or a combination of tiles:read and places:read.

Viewing & Managing Tokens

1. Go to Tokens in the console sidebar
2. View all tokens for your organization with:
   • Token name
   • Scopes granted
   • Creation date
   • Last used date

Token Settings

All organization members can manage token settings including rate limits and scopes.

Revoking a Token

If a token is compromised or no longer needed, revoke it immediately:

1. Go to Tokens in the console sidebar
2. Find the token in the list
3. Click Revoke
4. Confirm the revocation

Revoked tokens stop working immediately. Any in-flight requests using the token will fail with a 401 Unauthorized error.

Token Exchange for Frontend Apps

Never embed long-lived API tokens in client-side code. Instead, use token exchange to get short-lived access tokens.

How It Works

1. Your backend server holds the long-lived API token
2. When a user loads your map, your backend exchanges it for a short-lived token (1–4 hours)
3. Pass the short-lived token to the frontend
4. The short-lived token expires naturally. Repeat the exchange as needed.

Quick Example

# Your backend exchanges the long-lived token for a short-lived one
curl -X POST "https://api.geog.dev/v1/auth/token" \
  -H "Authorization: Bearer YOUR_LONG_LIVED_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"ttl": 3600, "scope": "tiles:read"}'

Response:

{
  "access_token": "eyJhbGc...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "expires_at": "2025-12-29T15:30:00Z",
  "scope": "tiles:read"
}

For full implementation details, see the Token Exchange API reference and Token Exchange Guide.

Security Best Practices

• Use environment variables. Never hard-code tokens in source code.
• Scope minimally. Only grant the scopes your application needs.
• Rotate regularly. Create new tokens periodically and revoke old ones.
• Use token exchange for frontends. Never expose long-lived tokens in client-side JavaScript.
• Revoke compromised tokens immediately. Don't wait; revoke first, investigate later.
• Use separate tokens per environment. Create different tokens for development, staging, and production.

Token Permissions

Next Steps

• Token Exchange API: Full endpoint specification
• Token Exchange Guide: Implementation examples for MapLibre, Leaflet, etc.
• Authentication: How API authentication works
• Best Practices: General API integration guidelines