Authentication

The Payroc API uses Bearer tokens to authenticate requests. Use our Identity Service to generate a Bearer token, and then send the token in the header of your requests to our API.

Each Bearer token expires after one hour, and you must generate a new Bearer token before the previous one expires.

Request

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

To generate a Bearer token, include your API key in the x-api-key parameter in the header of a POST request to the Identity Service endpoint.

Endpoint: https://identity.payroc.com/authorize

Note: To test your integration, create a test API key in the Developer Portal. We automatically send requests that use a test API key to our test environment, so you don't need to change the endpoint.

Example request

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

Response

If your request is successful, we generate a Bearer token and return it in the access_token field in the response. The response contains the following fields:

Example response

{
  "access_token": "eyJhbGc....adQssw5c",
  "expires_in": 3600,
  "scope": "service_a service_b",
  "token_type": "Bearer"
}

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.