Zum Hauptinhalt springen
Version: aktuell

Authentication Flow

This page describes how client applications authenticate to the VaultPAM control-plane REST API.

Overview​

VaultPAM supports two credential types:

Credential typeUse caseLifetime
Session tokenInteractive or short-lived automationControlled by expires_in field in the response
Personal Access Token (PAT)Long-lived integrations, CI/CD pipelinesUp to PAT_ABSOLUTE_MAX_TTL_DAYS (180 days)

Both types are Bearer tokens carried in the Authorization header on every request.

Session Token Acquisition​

Step 1 — POST /api/v1/auth/login​

POST /api/v1/auth/login
Content-Type: application/json

{
  "email": "operator@example.com",
  "password": "<password>"
}

Successful response (200):

{
  "access_token": "eyJ...",
  "expires_in": 3600
}

The expires_in field is the authoritative token lifetime in seconds. Treat this value as the source of truth for your token expiry logic — do not rely on any hard-coded constant.

Error response: All authentication failures return a uniform AUTH_FAILED error regardless of the actual failure reason (wrong password, unknown email, locked account). This is intentional — VaultPAM does not expose which part of the credential was invalid.

{
  "error": "AUTH_FAILED",
  "message": "Authentication failed."
}

Step 2 — Identify the active organization​

GET /api/v1/org/memberships
Authorization: Bearer <access_token>

Response:

{
  "active_org_id": "org_01HXZ...",
  "memberships": [
    { "org_id": "org_01HXZ...", "role": "operator" }
  ]
}

Use active_org_id as the value for the X-Active-Org-Id header on subsequent requests.

Making Authenticated Requests​

Include both headers on every API call:

Authorization: Bearer <access_token>
X-Active-Org-Id: <active_org_id>

Example:

GET /api/v1/safes
Authorization: Bearer eyJ...
X-Active-Org-Id: org_01HXZ...

Session Token Expiry​

Session tokens are not refreshable. There is no refresh endpoint — a request to /api/v1/auth/refresh returns 404. When your token expires, re-authenticate by calling POST /api/v1/auth/login again.

Your client should:

  1. Store the expires_in value from the login response.
  2. Re-authenticate before the token expires (recommended: subtract 60 seconds as a buffer).
  3. Retry the original request with the new token.
No automatic refresh

VaultPAM does not support OAuth-style refresh tokens. Re-login is required on expiry.

Logout​

Invalidate a session token immediately:

POST /api/v1/auth/logout
Authorization: Bearer <access_token>
X-Active-Org-Id: <active_org_id>

Response: 204 No Content

Personal Access Tokens (PATs)​

PATs are long-lived tokens for automation and integrations. They carry the prefix pat_AIC_.

Create a PAT​

POST /api/v1/auth/api-tokens
Authorization: Bearer <access_token>
X-Active-Org-Id: <active_org_id>
Content-Type: application/json

{
  "name": "ci-pipeline-token",
  "scopes": ["safes.read"],
  "expires_in_days": 90
}

The token value is returned once at creation time and cannot be retrieved again.

Revoke a PAT​

DELETE /api/v1/auth/api-tokens/{token_id}
Authorization: Bearer <access_token>
X-Active-Org-Id: <active_org_id>

Response: 204 No Content

Scope enforcement

Scope enforcement is being rolled out per endpoint family. Calls with a scoped PAT to an endpoint outside the token's declared scopes may return 403. Use the minimum scopes needed for your use case.

Token Storage​

Store tokens securely

Tokens provide full API access within their granted scopes. Mishandled tokens can lead to unauthorized access.

Required practices:

  1. Never commit tokens to source control. Even in private repositories, tokens in committed code are a persistent security risk. Use environment variables or a secrets manager.
  2. Use an OS keychain or secrets manager in production. Examples: AWS Secrets Manager, HashiCorp Vault, macOS Keychain, Linux kernel keyring.
  3. Never log token values. Review your logging configuration to ensure tokens in headers or request bodies are masked.
  4. Revoke tokens when they are no longer needed. Use DELETE /api/v1/auth/api-tokens/{token_id} for PATs. Session tokens expire automatically but should be treated as revocable.
  5. Configure secret-scanning tools to detect the pat_AIC_ prefix. This prefix is present on all VaultPAM PATs and allows tools like GitHub Advanced Security to flag accidental exposure.

Next steps​