API v1 authentication

Create a token with POST /oauth/token using the OAuth 2.0 client credentials grant. Authenticate with HTTP Basic using your client_id as the username and client_secret as the password, and send grant_type=client_credentials as a form-encoded body:

curl -X POST https://dev-api.wisedocs.ai/oauth/token \
  -u '<client_id>:<client_secret>' \
  -d grant_type=client_credentials

A successful response returns the token:

{"access_token": "<jwt>", "token_type": "Bearer", "expires_in": 300, "scope": "cases:read cases:write"}

Send access_token as Authorization: Bearer <access_token>. Tokens cannot be refreshed; request a new one when expires_in runs out.

Every protected /api/v1 request also requires the API Gateway key in the x-api-key header. OAuth discovery, token, introspection, and revocation endpoints do not require x-api-key.

API v1 request bodies, response bodies, and query parameters use camelCase.

Use the same HTTP Basic credentials (client_id and client_secret) with POST /oauth/introspect and POST /oauth/revoke. A client can inspect or revoke only tokens it issued.

Introspection reports inactive, expired, or revoked tokens as {"active": false}. Revocation is idempotent.

A 503 Service Unavailable response means token status could not be confirmed. Retry later instead of treating the token as valid or successfully revoked.

Wisedocs provides a client_id and client_secret for each integration. Every protected /api/v1 operation requires a scope, and the scope field in the token response lists the scopes granted to the client.

A request whose token lacks the operation's scope fails with 403 Forbidden:

{"error": {"message": "The access token does not grant the `cases:write` scope", "code": "insufficient_scope"}}

A missing, malformed, expired, or revoked token returns 401 Unauthorized with a WWW-Authenticate: Bearer ... error="invalid_token" header.

API v1 requires API v1 client credentials; API v0 credentials and tokens are not accepted on /api/v1.

If your account restricts case visibility by team, include case.teams in POST /api/v1/cases. Use GET /api/v1/teams to look up team UUIDs by name, username, or email.