Authentication

Vault uses OAuth 2.0 / OIDC. Get an access token from your tenant's token endpoint and send it as a Bearer token on every request.

Authorization: Bearer <access_token>

Tokens are short‑lived (expires_in: 300, 5 minutes) and scoped to one tenant - a token without a tenant claim is rejected with 401.

There are two flows:

• Client credentials - for backend services and integrations (no user).

• Authorization code - for apps acting on behalf of a signed‑in user.

account, environment, tenant, client_id and client_secret are provided by Docbyte.

Client credentials

curl -X POST "https://keycloak.{account}.{environment}.docbyte.cloud/realms/{tenant}/protocol/openid-connect/token"
  -H "Content-Type: application/x-www-form-urlencoded"
  -d "grant_type=client_credentials"
  -d "client_id={client_id}"
  -d "client_secret={client_secret}"
  -d "scope=openid"

Response -

{
  "access_token": "{access_token}",
  "expires_in": 300,
  "token_type": "Bearer"
}

No refresh token is issued - request a new token before the current one expires.

Example in Postman

Authorization code

Standard OIDC authorization code flow.

Your app must be registered as a client first.

Provide Docbyte with:

• Redirect URI(s) - exact callback URLs. Anything not on the allowlist is rejected.

• Web origins - for browser/SPA clients.

Docbyte will provide the client_id.

1. Redirect the user's browser to the authorize endpoint:

   https://keycloak.{account}.{environment}.docbyte.cloud/realms/{tenant}/protocol/openid-connect/auth?response_type=code&client_id={client_id}&redirect_uri={redirect_uri}&scope=openid%20email%20profile&state={state}
   

2. The user signs in, which redirects the browser back to {redirect_uri}?code={code}&state={state}.

3. Exchange the code for tokens:

   Bash

   curl -X POST "https://keycloak.{account}.{environment}.docbyte.cloud/realms/{tenant}/protocol/openid-connect/token"
     -H "Content-Type: application/x-www-form-urlencoded"
     -d "grant_type=authorization_code"
     -d "code={code}"
     -d "redirect_uri={redirect_uri}"
     -d "client_id={client_id}"
   

4. Response -

   {
     "access_token": "{access_token}",
     "expires_in": 300,
     "refresh_expires_in": 1800,
     "refresh_token": "{refresh_token}",
     "id_token": "{id_token}",
     "token_type": "Bearer",
     "scope": "openid email profile groups tenant"
   }
   

Errors

{ "message": null, "code": "NOT_AUTHORIZED" }

401 - missing, expired, or malformed token, or no tenant claim.

Calling the API

curl "https://{vault-api-host}/api/v1/..."
  -H "Authorization: Bearer <access_token>"