Authentication¶

The HCP Unified API uses OAuth2 password flow to issue JWT bearer tokens. Credentials provided at login are encrypted into the token and forwarded to HCP on every subsequent API request -- the API itself does not store passwords.

from rahcp_client import HCPClient
async with HCPClient(endpoint="http://localhost:8000/api/v1",
                      username="admin", password="secret", tenant="dev-ai") as client:
    await client.s3.list_buckets()  # authenticated automatically

Auth flow¶

1. Login by sending your credentials to POST /api/v1/auth/token.
2. Receive a JWT access token in the response.
3. Include the token in the Authorization: Bearer <token> header on all subsequent requests.
4. The API decodes the JWT on each request and uses the embedded credentials to authenticate against HCP.

Username formats¶

When logging in with tenant/username, the API extracts the tenant name and routes MAPI requests to the correct tenant context. The tenant can also be provided as a separate tenant form field (used by the frontend); the explicit field takes priority over the slash notation.

Endpoints¶

POST /api/v1/auth/token¶

Request body (form data, application/x-www-form-urlencoded):

Response (200 OK):

{
  "access_token": "eyJhbGciOiJIUzI1NiIs...",
  "token_type": "bearer"
}

JWT details¶

Token payload¶

HCP auth types¶

The API supports two HCP authentication mechanisms, configured via the HCP_AUTH_TYPE environment variable (default: hcp):

This setting controls how the API authenticates to HCP on behalf of the user. It does not affect how clients authenticate to this API (which always uses JWT bearer tokens).

Code examples¶

Login and use the token¶

# Login (system-level)
curl -X POST http://localhost:8000/api/v1/auth/token \
  -d "username=admin&password=mypassword"

# Login (tenant-scoped, using slash notation)
curl -X POST http://localhost:8000/api/v1/auth/token \
  -d "username=dev-ai/admin&password=mypassword"

# Login (tenant-scoped, using explicit tenant field)
curl -X POST http://localhost:8000/api/v1/auth/token \
  -d "username=admin&password=mypassword&tenant=dev-ai"

# Use the token for authenticated requests
TOKEN="eyJhbGciOiJIUzI1NiIs..."

# List S3 buckets
curl -H "Authorization: Bearer $TOKEN" \
  http://localhost:8000/api/v1/buckets

# List tenants (system admin)
curl -H "Authorization: Bearer $TOKEN" \
  http://localhost:8000/api/v1/mapi/tenants

Swagger UI¶

The interactive documentation at /docs includes an Authorize button (lock icon, top-right). Enter your credentials there to authenticate all try-it-out requests:

• Username: admin (system-level) or dev-ai/admin (tenant-scoped)
• Password: your HCP password

Error responses¶