--- agentTools: projectIndex: https://percolate.dev/llms.txt --- # /auth/v5/token/ The access token request must be authenticated utilizing the "HTTP Basic authentication scheme" as defined in [RFC 2617](http://tools.ietf.org/html/rfc2617#section-2). This endpoint supports both standard submission using `application/x-www-form-urlencoded` and `application/json` content types for convenience. Your Client ID and Client Secret must be joined by ":", then Base64 encoded, and included in the `Authorization` request header (ex. `base64("{client_id}:{client_secret}")`). For example, for a Client ID "client:9001" and Secret "thesystemofrecord", the following header would be expected once Base64 encoded (i.e. `base64("client:9001:thesystemofrecord")``): Authorization: Basic Y2xpZW50OjkwMDE6dGhlc3lzdGVtb2ZyZWNvcmQ= If authenticating via Postman, you would choose "Basic Auth" as the Auth Type, the Client ID (e.g. "client:9001") as the username, and the Client Secret as the password (e.g. "thesystemofrecord"). Postman handles the Base64 encoding for you. # OpenAPI definition ```json { "openapi": "3.0.0", "info": { "title": "Percolate V5 OpenAPI Specification", "description": "The Percolate API is RESTful in nature. Our APIs use HTTP resource-oriented URLs. HTTP methods are used to issue requests. HTTP response codes are used to indicate API successes or failures. All API requests and responses are in JSON representation. This document describes the HTTP resources and methods that form the Percolate API.\n", "version": "1.0.0", "contact": { "name": "Percolate Engineering" } }, "servers": [ { "url": "https://percolate.com" }, { "url": "https://devolate.com" } ], "tags": [ { "name": "Auth Token" } ], "components": { "securitySchemes": { "oauth2": { "description": "Percolate supports OAuth 2.0 for authenticating all API requests.\n", "type": "oauth2", "flows": { "authorizationCode": { "authorizationUrl": "https://percolate.com/api/v5/authorize", "tokenUrl": "https://percolate.com/api/v5/token", "scopes": {} } } }, "httpBasic": { "description": "Described by [RFC 2617](http://tools.ietf.org/html/rfc2617#section-2), client must authenticate itself by including an identifier and a secret, base-64 encoded.\n", "type": "apiKey", "in": "header", "name": "Authorization" } } }, "security": [ { "oauth2": [] } ], "paths": { "/auth/v5/token/": { "post": { "operationId": "createAccessToken", "description": "The access token request must be authenticated utilizing the \"HTTP Basic authentication scheme\" as defined in [RFC 2617](http://tools.ietf.org/html/rfc2617#section-2). This endpoint supports both standard submission using `application/x-www-form-urlencoded` and `application/json` content types for convenience.\nYour Client ID and Client Secret must be joined by \":\", then Base64 encoded, and included in the `Authorization` request header (ex. `base64(\"{client_id}:{client_secret}\")`).\nFor example, for a Client ID \"client:9001\" and Secret \"thesystemofrecord\", the following header would be expected once Base64 encoded (i.e. `base64(\"client:9001:thesystemofrecord\")``):\n\n Authorization: Basic Y2xpZW50OjkwMDE6dGhlc3lzdGVtb2ZyZWNvcmQ=\n\nIf authenticating via Postman, you would choose \"Basic Auth\" as the Auth Type, the Client ID (e.g. \"client:9001\") as the username, and the Client Secret as the password (e.g. \"thesystemofrecord\"). Postman handles the Base64 encoding for you.\n", "tags": [ "Auth Token" ], "security": [ { "httpBasic": [] }, { "oauth2": [ "token:create" ] } ], "servers": [ { "url": "https://percolate.com/auth" } ], "requestBody": { "content": { "application/json": { "schema": { "oneOf": [ { "title": "Authorization Code", "type": "object", "description": "Post data to create a new access token for an Authorization Code grant.", "example": { "code": "n9TcZD5Io-ikZhBohcLFBVvbShc-8rOVepAOnMcx4NwnIo0gJzwUC05ySOnA-Pr6", "grant_type": "authorization_code" }, "required": [ "code", "grant_type" ], "additionalProperties": false, "properties": { "code": { "description": "The authorization code received from Percolate..", "type": "string", "pattern": "^[A-Za-z0-9\\-_]{64}$" }, "grant_type": { "description": "Grant type must be `authorization_code`", "type": "string", "enum": [ "authorization_code" ] } } }, { "title": "Client Credentials", "type": "object", "description": "Post data to create a new access token for a Client Credentials grant.", "example": { "grant_type": "client_credentials" }, "required": [ "grant_type" ], "additionalProperties": false, "properties": { "grant_type": { "description": "Grant type must be `client_credentials`", "type": "string", "enum": [ "client_credentials" ] } } }, { "title": "Refresh Token", "type": "object", "description": "Post data to refresh an existing Auth Code token.", "example": { "grant_type": "refresh_token", "refresh_token": "QxO1Puihu5IPyiTyLyHrM7b4Ju0J08Lm7_P4hBPXyBKtBa__IGPjM7L8MTlfs62v" }, "required": [ "grant_type", "refresh_token" ], "additionalProperties": false, "properties": { "grant_type": { "description": "Grant type must be `refresh_token`", "type": "string", "enum": [ "refresh_token" ] }, "refresh_token": { "description": "Value used to refresh this token. Either after `expires_at` has expired or any time before.", "type": "string", "pattern": "^[A-Za-z0-9\\-_]{64}$" } } } ] }, "examples": { "request": { "value": { "code": "n9TcZD5Io-ikZhBohcLFBVvbShc-8rOVepAOnMcx4NwnIo0gJzwUC05ySOnA-Pr6", "grant_type": "authorization_code" } } } } }, "required": false }, "responses": { "201": { "description": "A new access token was granted.", "content": { "application/json": { "schema": { "title": "Token", "description": "Access tokens may be refreshed for 30 days after its last `updated_at` time.", "type": "object", "required": [ "access_token", "expires_in", "grant_id", "id", "refresh_token", "token_type", "updated_at", "user_id" ], "additionalProperties": false, "properties": { "authorized_tenant_id": { "description": "The tenant whose data this token allows access to (coming soon).", "type": "string" }, "access_token": { "description": "The `access_token` used to authenticate api requests.", "type": "string", "pattern": "^[A-Za-z0-9\\-_]{64}$" }, "expires_in": { "description": "Time after which this token will be invalid, in seconds", "type": "integer" }, "grant_id": { "description": "The grant ID that authorizes this access token", "type": "string", "pattern": "^grant:\\d+$" }, "id": { "description": "The token ID", "type": "string", "pattern": "^token:.+" }, "refresh_token": { "description": "Value used to refresh this token. Either after `expires_at` has expired or any time before.", "type": "string", "pattern": "^[A-Za-z0-9\\-_]{64}$" }, "token_type": { "description": "All tokens issued by this API are \"bearer\" tokens described in Section 7.1 of [RFC6749](https://tools.ietf.org/html/rfc6749#section-7.1)..", "type": "string", "enum": [ "bearer" ] }, "updated_at": { "title": "updated_At", "description": "An absolute datetime indicating when this resource was last modified.", "example": "2014-06-10T00:00:00Z", "format": "date-time", "type": "string" }, "user_id": { "title": "user_id", "type": "string", "description": "Percolate user that this token grants access to.", "pattern": "^user:\\d+$" } } }, "examples": { "response": { "value": { "access_token": "pBkgJV_cEVKESx4SH7wm-kYdfVgnyhDGCdqoRtygQE7HawAApeaNjN1vwAuboKXE", "expires_in": 2592000, "grant_id": "grant:1", "id": "token:1", "refresh_token": "QxO1Puihu5IPyiTyLyHrM7b4Ju0J08Lm7_P4hBPXyBKtBa__IGPjM7L8MTlfs62v", "token_type": "bearer", "updated_at": "2000-01-01T00:00:00Z", "user_id": "user:1" } } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string", "description": "- invalid_request - The request is missing a required parameter, includes an unsupported parameter value (other than grant type), repeats a parameter, includes multiple credentials, utilizes more than one mechanism for authenticating the client, or is otherwise malformed. - invalid_client - Client authentication failed (e.g., unknown client, no client authentication included, or unsupported authentication method). - invalid_grant - The provided authorization grant (e.g., authorization code, resource owner credentials) or refresh token is invalid, expired, revoked, does not match the redirection URI used in the authorization request, or was issued to another client. - unauthorized_client - The authenticated client is not authorized to use this authorization grant type. - unsupported_grant_type - The authorization grant type is not supported by the authorization server.\n", "enum": [ "invalid_request", "invalid_client", "invalid_grant", "unauthorized_client", "unsupported_grant_type" ] } } }, "examples": { "response": { "value": { "error": "invalid_grant" } } } } } }, "401": { "description": "User is not authorized to create a token.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string", "description": "- invalid_request - The request is missing a required parameter, includes an unsupported parameter value (other than grant type), repeats a parameter, includes multiple credentials, utilizes more than one mechanism for authenticating the client, or is otherwise malformed. - invalid_client - Client authentication failed (e.g., unknown client, no client authentication included, or unsupported authentication method). - invalid_grant - The provided authorization grant (e.g., authorization code, resource owner credentials) or refresh token is invalid, expired, revoked, does not match the redirection URI used in the authorization request, or was issued to another client. - unauthorized_client - The authenticated client is not authorized to use this authorization grant type. - unsupported_grant_type - The authorization grant type is not supported by the authorization server.\n", "enum": [ "invalid_request", "invalid_client", "invalid_grant", "unauthorized_client", "unsupported_grant_type" ] } } }, "examples": { "response": { "value": { "error": "invalid_grant" } } } } } }, "403": { "description": "User is forbidden from refreshing or creating a token.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string", "description": "- invalid_request - The request is missing a required parameter, includes an unsupported parameter value (other than grant type), repeats a parameter, includes multiple credentials, utilizes more than one mechanism for authenticating the client, or is otherwise malformed. - invalid_client - Client authentication failed (e.g., unknown client, no client authentication included, or unsupported authentication method). - invalid_grant - The provided authorization grant (e.g., authorization code, resource owner credentials) or refresh token is invalid, expired, revoked, does not match the redirection URI used in the authorization request, or was issued to another client. - unauthorized_client - The authenticated client is not authorized to use this authorization grant type. - unsupported_grant_type - The authorization grant type is not supported by the authorization server.\n", "enum": [ "invalid_request", "invalid_client", "invalid_grant", "unauthorized_client", "unsupported_grant_type" ] } } }, "examples": { "response": { "value": { "error": "invalid_grant" } } } } } }, "415": { "description": "Invalid media type", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string", "description": "- invalid_request - The request is missing a required parameter, includes an unsupported parameter value (other than grant type), repeats a parameter, includes multiple credentials, utilizes more than one mechanism for authenticating the client, or is otherwise malformed. - invalid_client - Client authentication failed (e.g., unknown client, no client authentication included, or unsupported authentication method). - invalid_grant - The provided authorization grant (e.g., authorization code, resource owner credentials) or refresh token is invalid, expired, revoked, does not match the redirection URI used in the authorization request, or was issued to another client. - unauthorized_client - The authenticated client is not authorized to use this authorization grant type. - unsupported_grant_type - The authorization grant type is not supported by the authorization server.\n", "enum": [ "invalid_request", "invalid_client", "invalid_grant", "unauthorized_client", "unsupported_grant_type" ] } } }, "examples": { "response": { "value": { "error": "invalid_grant" } } } } } } } } } }, "x-readme": { "explorer-enabled": true, "proxy-enabled": true }, "_id": { "buffer": { "0": 93, "1": 205, "2": 195, "3": 215, "4": 75, "5": 71, "6": 148, "7": 0, "8": 18, "9": 126, "10": 128, "11": 225 } } } ```