Authentication

View as Markdown

The Payroc API uses Bearer tokens to authenticate requests. To generate a Bearer token, include your API token in the ‘x-api-key’ parameter in the header of a request to the Payroc Identity Service.

Important: Use HTTPS for all requests to the Payroc API. We reject all HTTP requests, and all requests that are not properly authenticated.

Request

Identity Service endpoints:

EndpointPrefixURL
Testidentity.uat.https://identity.uat.payroc.com/authorize
Productionidentity.https://identity.payroc.com/authorize
$curl --location --request POST  'https://identity.payroc.com/authorize' --header 'x-api-key: <api key>'

Response

1{
2  "access_token": "eyJhbGc....adQssw5c",
3  "expires_in": 3600,
4  "scope": "service_a service_b",
5  "token_type": "Bearer"
6}

Request headers

Include the following headers in each request to the Payroc API:

  • Content-Type: Include application/json.
  • Authorization: Include your Bearer token.
  • Idempotency-Key: Include a UUID v4 to make POST and PATCH requests idempotent.
$curl
$-H "Content-Type: application/json"
$-H "Authorization: Bearer <access token>"
$-H "Idempotency-Key: <UUID v4>"

Note: Some endpoints require a different value for Content-Type. Check the individual guide for exceptions.

API key best practices

  • Grant API keys with the least amount of privilege to carry out target tasks.
  • Do not share API keys.
  • Do not use API keys in publicly accessible areas, for example, client-side code.