# Authentication

To ensure no spooky stuff happens.

## Exchange credentials for token. (Example only)

> You will be provided with a client\_id and a client\_secret which you'll use to authenticate yourself in the system.\
> The first thing you need to do is to get access token which you will then use for further requests. \
> When it expires, you will need to request another one.\
> Multiple tokens can be active at once. \
> \
> Supported types:\
> \+ \`client\_credentials\`\
> Once you have a valid access token, you will need to use it to sign all requests made to the Prio API.\
> \
> This is done by providing Authorization HTTP header along with each of your requests in the following format:\
> \
> \+  \`Authorization:\` \`\<token\_type>\` \`\<access\_token>\`\
> \
> If this header is not present in the request, the service will reject the request by returning the\
> HTTP error code 400 and respond with an appropriate error message.\
> \> Please do not manually perform this operation, we highly encourage you to use an existing OAuth library for your specific language.\
> \
> \> Make sure to call this endpoint only in case your current token has expired to reduce roundtrips and overal latency.

```json
{"openapi":"3.0.0","info":{"title":"Distributor API Specification V3.8","version":"3.8.0"},"tags":[{"name":"Authentication","description":"To ensure no spooky stuff happens."}],"servers":[{"url":"https://{environment}.prioticket.com/{version}/distributor","description":"Prio environments.","variables":{"environment":{"description":"* `distributor-api` - Production server; used for real transactions.\n\n* `sandbox-distributor-api` - Sandbox server.\n\n* `staging-distributor-api` - Pre-Production server; used for testing (UAT), verification, demo and certification.\n\n* `internal-distributor-api` - Internal server; reserved for internal use.\n","default":"staging-distributor-api","enum":["distributor-api","sandbox-distributor-api","staging-distributor-api","internal-distributor-api"]},"version":{"description":"Api version.","default":"v3.8","enum":["v3.8"]}}}],"security":[{"basicAuth":[]}],"components":{"securitySchemes":{"basicAuth":{"type":"http","description":"Basic Auth used for retrieving a JWT token using the /oauth2/token endpoint (Sample Only) and Webhook security. For the other endpoints, the OAuth2 flow should be used instead.","scheme":"basic"}},"schemas":{"ClientCredentialsGrantResponse":{"title":"Client Credentials Grant Response","type":"object","additionalProperties":false,"properties":{"access_token":{"title":"Access Token","description":"The access token issued by the authorization server.","type":"string"},"token_type":{"title":"Token Type","description":"The type of the token issued.","type":"string"},"expires_in":{"title":"Expires In","description":"The lifetime in seconds of the access token. For example, the value \"3600\" denotes that the access token will expire in one hour from the time the response was generated.","type":"integer"},"scope":{"title":"Scope","description":"OPTIONAL, if identical to the scope requested by the client; otherwise, REQUIRED.","type":"string"}},"required":["access_token","token_type","expires_in"]},"OAuthErrorModel":{"title":"OAuth Error Model","description":"OAuth error model.","type":"object","properties":{"error":{"$ref":"#/components/schemas/OAuthErrorCodes"},"error_description":{"title":"Error Description","description":"Human-readable ASCII [[USASCII]](https://tools.ietf.org/html/rfc6749#ref-USASCII) text providing additional information, used to assist the client developer in understanding the error that occurred.","type":"string"},"error_uri":{"title":"Error URI","description":"A URI identifying a human-readable web page with information about the error, used to provide the client developer with additional information about the error.","type":"string"}},"required":["error"]},"OAuthErrorCodes":{"title":"OAuth Error Codes","description":"The authorization server responds with an HTTP 400 (Bad Request) status code (unless specified otherwise) and includes the following parameters with the response.\n\nValues for the parameters MUST NOT include characters outside the set %x20-21 / %x23-5B / %x5D-7E.\n\n   Error:\n   * `invalid_request` (string) - 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. \n   * `invalid_client` (string) - Client authentication failed (e.g., unknown client, no client authentication included, or unsupported authentication method). The authorization server MAY return an HTTP 401 (Unauthorized) status code to indicate which HTTP authentication schemes are supported. If the client attempted to authenticate via the `Authorization` request header field, the authorization server MUST respond with an HTTP 401 (Unauthorized) status code and include the `WWW-Authenticate` response header field matching the authentication scheme used by the client.\n   * `invalid_grant` (string) - 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.\n   * `unauthorized_client` (string) - The authenticated client is not authorized to use this authorization grant type.\n   * `unsupported_grant_type` (string) - The authorization grant type is not supported by the authorization server.\n   * `invalid_scope` (string) - `The requested scope is invalid, unknown, malformed, or exceeds the scope granted by the resource owner.","type":"string","enum":["invalid_request","invalid_client","invalid_grant","unauthorized_client","unsupported_grant_type","invalid_scope"]},"ErrorModel":{"title":"Error Model","description":"Error model.","type":"object","readOnly":true,"properties":{"error":{"title":"Error Code","description":"The error code which occured.\n\nAs our API has over 1000+ unique error codes (grouped by HTTP status). We discourage implementing individual errors on your customer front-end interface and suggest a catch-all clause for each HTTP status code instead.\n\nErrors can be shown directly to the customer using the `error_message`, while more specific details explaining the problem will be provided in the `errors` object.\nWe recommend a combination of `error_message` and `error_reference` when communicating with the customer and API support.\n","type":"string","readOnly":true},"error_reference":{"title":"Error Reference","description":"Unique reference linked to this error.\n\nWe recommend showing this reference to the customer to allow for better issue tracking.\n","type":"string","readOnly":true},"error_message":{"title":"Error Message","description":"Customer friendly error message which can be shown on your front-end.\n","type":"string","readOnly":true},"error_description":{"title":"Error Description","description":"Human-readable ASCII [[USASCII]](https://tools.ietf.org/html/rfc6749#ref-USASCII) text providing additional information, used to assist the client developer in understanding the error that occurred.","type":"string","readOnly":true},"error_uri":{"title":"Error URI","description":"A URI identifying a human-readable web page with information about the error, used to provide the client \ndeveloper with additional information about the error.","type":"string","readOnly":true},"errors":{"title":"Error Messages","description":"Specific messages indicating one or more problems.","type":"array","readOnly":true,"items":{"title":"Error Message","description":"Specific message indicating a problem.","type":"string","readOnly":true}}},"required":["error","error_reference"]},"ClientCredentialsGrantRequest":{"title":"Client Credentials Grant Request","type":"object","additionalProperties":false,"properties":{"grant_type":{"title":"Grant Type","description":"Value MUST be set to \"client_credentials\".","type":"string"},"scope":{"title":"Scope","description":"The scope of the access request.","type":"string"}},"required":["grant_type"]}},"responses":{"MethodNotAllowed":{"description":"Method Not Allowed\n\nThe HyperText Transfer Protocol (HTTP) 405 Method Not Allowed response status code indicates that the request method is known by the server but is not supported by the target resource.\n\nA request method is not supported for the requested\n      resource; for example, a GET request on a form that\n      requires data to be presented via POST, or a PUT request\n      on a read-only resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorModel"}}}},"NotAcceptable":{"description":"Not Acceptable\n\nThe HyperText Transfer Protocol (HTTP) 406 Not Acceptable client error response code indicates that the server cannot produce a response matching the list of acceptable values defined in the request's proactive content negotiation headers, and that the server is unwilling to supply a default representation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorModel"}}}},"UnprocessableEntity":{"description":"Unprocessable Entity\n\nThe HyperText Transfer Protocol (HTTP) 422 Unprocessable Entity response status code indicates that the server understands the content type of the request entity, and the syntax of the request entity is correct, but it was unable to process the contained instructions.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorModel"}}}},"LimitReached":{"description":"Too Many Requests\n\nThe HTTP 429 Too Many Requests response status code indicates the user has sent too many requests in a given amount of time (\"rate limiting\").","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorModel"}}}},"InternalServerError":{"description":"Internal Server Error\n\nThe HyperText Transfer Protocol (HTTP) 500 Internal Server Error response code indicates that the server encountered an unexpected condition that prevented it from fulfilling the request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorModel"}}}},"NotImplemented":{"description":"Not Implemented\n\nThe HyperText Transfer Protocol (HTTP) 501 Not Implemented server error response code means that the server does not support the functionality required to fulfill the request.\n\nThe server either does not recognize the request method, or it lacks the ability to fulfil the request. Usually this implies future availability (e.g., a new feature of a web-service API).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorModel"}}}},"BadGateway":{"description":"Bad Gateway\n\nThe HyperText Transfer Protocol (HTTP) 502 Bad Gateway server error response code indicates that the server, while acting as a gateway or proxy, received an invalid response from the upstream server.\n\nThe HTTP 502 Bad Gateway error is exclusively returned in case of problems during communication with the supplier or third-party system. ","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorModel"}}}},"ServiceUnavailable":{"description":"Service Unavailable\n\nThe HyperText Transfer Protocol (HTTP) 503 Service Unavailable server error response code indicates that the server is not ready to handle the request.\n\nThe HTTP 503 Service Unavailable error is exclusively returned in case of problems during internal communication.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorModel"}}}},"GatewayTimeout":{"description":"Gateway Timeout\n\nThe HyperText Transfer Protocol (HTTP) 504 Gateway Timeout server error response code indicates that the server, while acting as a gateway or proxy, did not get a response in time from the upstream server that it needed in order to complete the request.\n\nThe HTTP 504 Gateway Timeout error is exclusively returned in case of problems during communication with the supplier or third-party system. ","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorModel"}}}}}},"paths":{"/oauth2/token":{"post":{"description":"You will be provided with a client_id and a client_secret which you'll use to authenticate yourself in the system.\nThe first thing you need to do is to get access token which you will then use for further requests. \nWhen it expires, you will need to request another one.\nMultiple tokens can be active at once. \n\nSupported types:\n+ `client_credentials`\nOnce you have a valid access token, you will need to use it to sign all requests made to the Prio API.\n\nThis is done by providing Authorization HTTP header along with each of your requests in the following format:\n\n+  `Authorization:` `<token_type>` `<access_token>`\n\nIf this header is not present in the request, the service will reject the request by returning the\nHTTP error code 400 and respond with an appropriate error message.\n> Please do not manually perform this operation, we highly encourage you to use an existing OAuth library for your specific language.\n\n> Make sure to call this endpoint only in case your current token has expired to reduce roundtrips and overal latency.","summary":"Exchange credentials for token. (Example only)","operationId":"getToken","tags":["Authentication"],"parameters":[{"in":"header","name":"Authorization","schema":{"type":"string"},"required":false,"description":"The client sends HTTP requests with the Authorization header that contains the word Basic word followed by a space and a base64-encoded string username:password."}],"responses":{"200":{"description":"Successfully Authenticated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ClientCredentialsGrantResponse"}}}},"400":{"description":"Invalid Request\n\nThe request is missing a required parameter, includes an\n              unsupported parameter value (other than grant type),\n              repeats a parameter, includes multiple credentials,\n              utilizes more than one mechanism for authenticating the\n              client, or is otherwise malformed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OAuthErrorModel"}}}},"401":{"description":"Authentication Failed\n\nClient authentication failed (e.g., unknown client, no client authentication included, or unsupported authentication method). The authorization server MAY return an HTTP 401 (Unauthorized) status code to indicate which HTTP authentication schemes are supported. If the client attempted to authenticate via the `Authorization` request header field, the authorization server MUST respond with an HTTP 401 (Unauthorized) status code and include the `WWW-Authenticate` response header field matching the authentication scheme used by the client.","headers":{"WWW-Authenticate":{"description":"Defines the authentication method that should be used to gain access to a resource.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/OAuthErrorModel"}}}},"405":{"$ref":"#/components/responses/MethodNotAllowed"},"406":{"$ref":"#/components/responses/NotAcceptable"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/LimitReached"},"500":{"$ref":"#/components/responses/InternalServerError"},"501":{"$ref":"#/components/responses/NotImplemented"},"502":{"$ref":"#/components/responses/BadGateway"},"503":{"$ref":"#/components/responses/ServiceUnavailable"},"504":{"$ref":"#/components/responses/GatewayTimeout"}},"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ClientCredentialsGrantRequest"}}},"description":"Clients in possession of a client password MAY use the HTTP Basic authentication scheme \nas defined in [RFC2617](https://tools.ietf.org/html/rfc2617) to authenticate withthe authorization server.  \n\nThe client identifier is encoded using the \"application/x-www-form-urlencoded\" encoding algorithm, and the encoded value is used as the username; the client password is encoded using the same algorithm and used as the password.\n\nAlternatively, the authorization server supports including the client credentials in the request-body using the following parameters:Including the client credentials in the request-body using the two parameters is NOT RECOMMENDED and SHOULD be limited to clients unable to directly utilize the HTTP Basic authentication scheme (or other password-based HTTP authentication schemes). The parameters can only be transmitted in the request-body and MUST NOT be included in the request URI.","required":true}}}}}
```


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.prioticket.com/endpoints/authentication.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.