Token Exchange

Exchange long-lived API tokens for short-lived access tokens to securely use the Geog API in frontend applications (MapLibre GL JS, Leaflet, etc.) without exposing long-lived credentials.

Flow

sequenceDiagram
    participant Frontend
    participant Backend as Your Backend
    participant API as Geog API

    Backend->>API: POST /v1/auth/token + long-lived API token
    API->>Backend: Short-lived access token (1–4 hrs)
    Backend->>Frontend: Pass short-lived token
    Frontend->>API: Request tiles with short-lived token
    API->>Frontend: Vector tile data
    Note over Frontend: Token expires naturally. Repeat exchange as needed.

Endpoint

POST /v1/auth/token

Request

POST https://api.geog.dev/v1/auth/token
Authorization: Bearer {your_long_lived_api_token}
Content-Type: application/json

{
  "ttl": 3600,
  "scope": "tiles:read"
}

Parameters

Parameter	Type	Required	Description
`ttl`	number	No	Time-to-live in seconds. Default: 3600 (1 hour). Min: 1. Max: 14400 (4 hours).
`scope`	string	No	Space-separated scopes (must be subset of parent token). If omitted, inherits all parent scopes.

Response

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

Access Token Claims

Claim	Description
`sub`	Short-lived token ID (`tok_short_*`)
`org_id`	Organization ID from parent token
`scope`	Scopes (subset of parent token)
`token_type`	`api_token`
`aud`	API URL (audience)
`iss`	API URL (issuer)
`exp`	Expiration (1-14400 seconds from issue)

Characteristics

TTL range: 1-14400 seconds (1 second to 4 hours, default 3600)
Scope restriction: Must be subset of parent token scopes
No revocation: Tokens expire naturally by design
OAuth 2.0 compliant response format
Ideal for frontend mapping libraries (MapLibre, Leaflet, etc.)

Error Responses

Status	Error	Description
400	`invalid_ttl`	TTL must be between 1 and 14400 seconds
400	`invalid_request`	Request body must be valid JSON
401	`unauthorized`	Missing or invalid authentication
403	`invalid_scope`	Requested scopes exceed parent token permissions
500	`server_error`	Internal server error