Skip to main content

Authentication

Red Cloud CORE API authentication uses OAuth 2 client_credentials.

This is the first required step for every CORE API integration. No /api/core/* request works without a valid bearer token.

Canonical example values​

  • client_id: rc_test_client_123
  • client_secret: rc_secret_abc123
  • access_token: rc_token_example

Token endpoint​

  • route: POST /api/auth/token
  • supported grant type: client_credentials

Content type requirement​

Use form-encoded token requests. That matches the current implementation contract.

Authentication methods​

The token endpoint accepts either:

  1. HTTP Basic client authentication
  2. body client_id and client_secret

Example: HTTP Basic request​

curl -X POST "$BASE_URL/api/auth/token" \
  -u "rc_test_client_123:rc_secret_abc123" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=client_credentials"

Example: body credentials request​

curl -X POST "$BASE_URL/api/auth/token" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=client_credentials" \
  -d "client_id=rc_test_client_123" \
  -d "client_secret=rc_secret_abc123"

Successful token response​

{
  "access_token": "rc_token_example",
  "token_type": "bearer",
  "expires_in": 3600
}

Bearer token usage​

curl "$BASE_URL/api/core/whoami" \
  -H "Authorization: Bearer rc_token_example"

Use the same bearer token format for all /api/core/* requests.

Token lifecycle​

  • the token endpoint issues bearer tokens
  • tokens expire after 3600 seconds
  • integrations should refresh tokens before or when a 401 occurs
  • token validation also checks:
    • the API client is active
    • the parent CORE account is active
  • request a token during startup or first demand
  • cache the token with expiry metadata
  • refresh proactively when practical
  • on UNAUTHORIZED, request a new token and retry the protected request once

Retry guidance​

  • if token acquisition fails with 5xx, retry with normal client backoff
  • if token acquisition fails with invalid_client, do not blindly retry
  • if a CORE API call fails with expired or invalid token behavior, request a new token and retry the API call once

If repeated token refreshes fail, stop sending traffic and resolve credentials or account status first.

Common failure cases​

Invalid client credentials​

{
  "error": "invalid_client",
  "error_description": "Client authentication failed"
}

When this happens:

  • the client_id / client_secret pair is wrong
  • or the API client / CORE account is inactive

This is usually an operator or credential-management issue, not a transient outage.

Unsupported grant type​

{
  "error": "unsupported_grant_type",
  "error_description": "Only client_credentials is supported"
}

Missing credentials​

{
  "error": "invalid_request",
  "error_description": "client_id and client_secret are required"
}

Expired or invalid bearer token on CORE routes​

CORE routes do not return OAuth-style errors. They return the CORE error wrapper:

{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Invalid or missing bearer token",
    "details": {}
  },
  "requestId": "req_auth_001"
}

Malformed Authorization header​

If the bearer token is malformed or missing on /api/core/*, the route also responds with:

{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Invalid or missing bearer token",
    "details": {}
  },
  "requestId": "req_auth_001"
}

Practical authentication checklist​

Before moving to numbers or messaging, confirm:

  • token request returns 200
  • access_token is present
  • /api/core/whoami succeeds with the returned token
  • apiClientStatus is ACTIVE

If any of those fail, do not debug message-send behavior yet.