Skip to content

Exchange API key for short-lived access token

Request

Exchange a long-lived API key for a short-lived JWT access token (15 minutes).

This provides enhanced security by minimizing API key exposure.

Permissions and Scope:

  • All permissions, scopes, and home access are automatically determined by the API key
  • No need to specify permissions in the request body
  • The generated token will have all permissions associated with the API key

Rate Limits:

  • Tracked per client IP address, independent of API key
  • 10 requests per minute, applied consistently across all environments

Security Features:

  • Tokens expire automatically after 15 minutes
  • IP-based monitoring and abuse detection
  • Comprehensive audit logging

Usage Pattern:

  1. Exchange API key for access token at secure endpoint
  2. Use access token for API calls (never use API key directly)
  3. Re-exchange when token expires (every 15 minutes)

This follows OAuth 2.0 Token Exchange (RFC 8693) patterns.

Security
Bearer
Headers
User-Agentstring

Client identification for security monitoring

X-Forwarded-Forstring

Client IP address for rate limiting and monitoring

Bodyapplication/jsonrequired

Token exchange request parameters

grant_typestringrequired

Grant type for token exchange

Value:"api_key_exchange"
Example:"api_key_exchange"
api_keystring, >= 8 charactersrequired

API key to exchange for access token. The API key in MongoDB defines all permissions, scopes, and home access.

Example:"sk_live_abcd1234..."
POST
/auth/token/exchange
curl -i -X POST \
  https://data.logmycare.co.uk/openapi/auth/token/exchange \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>' \
  -H 'Content-Type: application/json' \
  -H 'User-Agent: string' \
  -H 'X-Forwarded-For: string' \
  -d '{
    "grant_type": "api_key_exchange",
    "api_key": "sk_live_abcd1234..."
  }'

Responses

Token exchange successful

Bodyapplication/json
access_tokenstringrequired

Short-lived JWT access token

Example:"eyJhbGciOiJIUzI1NiI..."
token_typestringrequired

Token type

Value:"Bearer"
Example:"Bearer"
expires_innumberrequired

Token expiration time in seconds

Example:900
scopeArray of stringsrequired

Granted permissions/scope

Example:
[
  "residents:read",
  "careplans:read"
]
issued_token_typestringrequired

Type of issued token

Example:"urn:ietf:params:oauth:token-type:jwt"
Response
{
  "access_token": "eyJhbGciOiJIUzI1NiI...",
  "token_type": "Bearer",
  "expires_in": 900,
  "scope": [
    "residents:read",
    "careplans:read"
  ],
  "issued_token_type": "urn:ietf:params:oauth:token-type:jwt"
}