{"templateId":"markdown","versions":[{"version":"v1","label":"API v1","link":"/api/authentication","default":true,"active":true,"folderId":"702acf7c"},{"version":"v0","label":"API v0 (Legacy)","link":"/api/v0/authentication","default":false,"active":false,"folderId":"702acf7c"}],"sharedDataIds":{"sidebar":"sidebar-api/@v0/sidebars.yaml"},"props":{"metadata":{"markdoc":{"tagList":[]},"type":"markdown"},"seo":{"title":"API v1 authentication","llmstxt":{"hide":true}},"dynamicMarkdocComponents":[],"compilationErrors":[],"ast":{"$$mdtype":"Tag","name":"article","attributes":{},"children":[{"$$mdtype":"Tag","name":"Heading","attributes":{"level":1,"id":"api-v1-authentication","__idx":0},"children":["API v1 authentication"]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"create-and-use-an-access-token","__idx":1},"children":["Create and use an access token"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Create a token with ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["POST /oauth/token"]}," using the OAuth 2.0 client credentials grant. Authenticate with HTTP Basic using your ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["client_id"]}," as the username and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["client_secret"]}," as the password, and send ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["grant_type=client_credentials"]}," as a form-encoded body:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"bash","header":{"controls":{"copy":{}}},"source":"curl -X POST https://dev-api.wisedocs.ai/oauth/token \\\n  -u '<client_id>:<client_secret>' \\\n  -d grant_type=client_credentials\n","lang":"bash"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["A successful response returns the token:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\"access_token\": \"<jwt>\", \"token_type\": \"Bearer\", \"expires_in\": 300, \"scope\": \"cases:read cases:write\"}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Send ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["access_token"]}," as ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Authorization: Bearer <access_token>"]},". Tokens cannot be refreshed; request a new one when ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["expires_in"]}," runs out."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Every protected ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["/api/v1"]}," request also requires the API Gateway key in the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["x-api-key"]}," header. OAuth discovery, token, introspection, and revocation endpoints do not require ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["x-api-key"]},"."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["API v1 request bodies, response bodies, and query parameters use camelCase."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"inspect-and-revoke-tokens","__idx":2},"children":["Inspect and revoke tokens"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Use the same HTTP Basic credentials (",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["client_id"]}," and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["client_secret"]},") with ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["POST /oauth/introspect"]}," and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["POST /oauth/revoke"]},". A client can inspect or revoke only tokens it issued."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Introspection reports inactive, expired, or revoked tokens as ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["{\"active\": false}"]},". Revocation is idempotent."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["A ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["503 Service Unavailable"]}," response means token status could not be confirmed. Retry later instead of treating the token as valid or successfully revoked."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"scopes-and-operation-access","__idx":3},"children":["Scopes and operation access"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Wisedocs provides a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["client_id"]}," and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["client_secret"]}," for each integration. Every protected ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["/api/v1"]}," operation requires a scope, and the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["scope"]}," field in the token response lists the scopes granted to the client."]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Scope"},"children":["Scope"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Operations"},"children":["Operations"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["cases:read"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["GET /api/v1/cases"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["GET /api/v1/cases/{caseUuid}"]}]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["cases:write"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["POST /api/v1/cases"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["PATCH /api/v1/cases/{caseUuid}"]}]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["files:read"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["GET /api/v1/cases/{caseUuid}/files/{fileUuid}"]}]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["files:write"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["POST /api/v1/cases/{caseUuid}/files"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["PATCH /api/v1/cases/{caseUuid}/files/{fileUuid}"]}]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["teams:read"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["GET /api/v1/teams"]}]}]}]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["A request whose token lacks the operation's scope fails with ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["403 Forbidden"]},":"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\"error\": {\"message\": \"The access token does not grant the `cases:write` scope\", \"code\": \"insufficient_scope\"}}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["A missing, malformed, expired, or revoked token returns ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["401 Unauthorized"]}," with a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["WWW-Authenticate: Bearer ... error=\"invalid_token\""]}," header."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["API v1 requires API v1 client credentials; API v0 credentials and tokens are not accepted on ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["/api/v1"]},"."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"assign-teams-when-creating-a-case","__idx":4},"children":["Assign teams when creating a case"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["If your account restricts case visibility by team, include ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["case.teams"]}," in ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["POST /api/v1/cases"]},". Use ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["GET /api/v1/teams"]}," to look up team UUIDs by ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["name"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["username"]},", or ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["email"]},"."]}]},"headings":[{"value":"API v1 authentication","id":"api-v1-authentication","depth":1},{"value":"Create and use an access token","id":"create-and-use-an-access-token","depth":2},{"value":"Inspect and revoke tokens","id":"inspect-and-revoke-tokens","depth":2},{"value":"Scopes and operation access","id":"scopes-and-operation-access","depth":2},{"value":"Assign teams when creating a case","id":"assign-teams-when-creating-a-case","depth":2}],"frontmatter":{"seo":{"title":"API v1 authentication"}},"lastModified":"2026-10-22T22:05:09.000Z","pagePropGetterError":{"message":"","name":""}},"slug":"/api/authentication","userData":{"isAuthenticated":false,"teams":["anonymous"]},"isPublic":true}