> For the complete documentation index, see [llms.txt](https://docs.payr.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.payr.com/authentication.md).

# Authentication

Payr uses token-based authentication for all API requests. There are two types of tokens:

#### Server Token (Server-to-Server)

Used for `/onboarding/`, `/user-login/`, and `/rotate-token/`. This is the long-lived API token provided by Payr or obtained via token rotation.

```
Authorization: Token your_server_api_token
```

#### User Session Token (Payment Interface / Session Inquiry)

Used for session queries and payment interfaces. This is the short-lived token returned by `/user-login/`, intended for the payment interface (iframe or SDK) and session queries.

```
Authorization: Token user_session_token_from_login
```

Contact **<support@mypayr.co.uk>** to receive your initial server API credentials.

> **Important:** Keep your server API token secure. Never expose it in client-side code or public repositories. The user session token is safe to pass to the client.

#### Token Rotation

For security, tokens should be rotated periodically using the `/rotate-token/` endpoint. When you rotate a token:

* A new token is generated and returned
* The old token remains valid for a grace period of 7-15 days
* This allows you to update your systems without downtime

## Rotate Server Token

> Generate a new server API token. The old token will remain valid for a grace period of 7-15 days, allowing you to update your systems without downtime.\
> \
> \*\*Note:\*\* This endpoint requires your current valid token to generate a new one.\
> \
> \### Example cURL Request\
> \`\`\`bash\
> curl -X POST <https://api.mypayr.co.uk/thirdparty/rotate-token/> \\\
> &#x20; -H "Authorization: Token 8f4e2b1a9c7d6e5f3b2a1c9d8e7f6a5b4c3d2e1f0a9b8c7d6e5f4a3b2c1d0e9f8" \\\
> &#x20; -H "Content-Type: application/json"\
> \`\`\`\
> \
> \### Example Response\
> \`\`\`json\
> {\
> &#x20; "token": "a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0u1v2w3x4y5z6a7b8c9d0e1f2",\
> &#x20; "old\_token\_expiry": "2024-01-22T14:30:00Z"\
> }\
> \`\`\`<br>

````json
{"openapi":"3.0.3","info":{"title":"Payr Integration API","version":"1.0.0"},"tags":[{"name":"Authentication","description":"Payr uses token-based authentication for all API requests. There are two types of tokens:\n\n### Server Token (Server-to-Server)\n\nUsed for `/onboarding/`, `/user-login/`, and `/rotate-token/`. This is the long-lived API token provided by Payr or obtained via token rotation.\n\n```\nAuthorization: Token your_server_api_token\n```\n\n### User Session Token (Payment Interface / Session Inquiry)\n\nUsed for session queries and payment interfaces. This is the short-lived token returned by `/user-login/`, intended for the payment interface (iframe or SDK) and session queries.\n\n```\nAuthorization: Token user_session_token_from_login\n```\n\nContact **support@mypayr.co.uk** to receive your initial server API credentials.\n\n> **Important:** Keep your server API token secure. Never expose it in client-side code or public repositories. The user session token is safe to pass to the client.\n\n### Token Rotation\n\nFor security, tokens should be rotated periodically using the `/rotate-token/` endpoint. When you rotate a token:\n- A new token is generated and returned\n- The old token remains valid for a grace period of 7-15 days\n- This allows you to update your systems without downtime\n"}],"servers":[{"url":"https://sandbox-api.mypayr.co.uk/thirdparty","description":"Sandbox server"},{"url":"https://api.mypayr.co.uk/thirdparty","description":"Production server"}],"security":[{"TokenAuth":[]}],"components":{"securitySchemes":{"TokenAuth":{"type":"apiKey","in":"header","name":"Authorization","description":"Server-to-server authentication token obtained via the rotate-token endpoint.\nInclude in the Authorization header as: `Authorization: Token <your_token>`\n"}},"schemas":{"RotateTokenResponse":{"type":"object","properties":{"token":{"type":"string","description":"The new authentication token"},"old_token_expiry":{"type":"string","format":"date-time","description":"Expiry datetime of the previous token (grace period)"}}},"ErrorResponse":{"type":"object","properties":{"error":{"type":"string","description":"Error message"},"detail":{"type":"string","description":"Detailed error information"}}}}},"paths":{"/rotate-token/":{"post":{"summary":"Rotate Server Token","description":"Generate a new server API token. The old token will remain valid for a grace period of 7-15 days, allowing you to update your systems without downtime.\n\n**Note:** This endpoint requires your current valid token to generate a new one.\n\n### Example cURL Request\n```bash\ncurl -X POST https://api.mypayr.co.uk/thirdparty/rotate-token/ \\\n  -H \"Authorization: Token 8f4e2b1a9c7d6e5f3b2a1c9d8e7f6a5b4c3d2e1f0a9b8c7d6e5f4a3b2c1d0e9f8\" \\\n  -H \"Content-Type: application/json\"\n```\n\n### Example Response\n```json\n{\n  \"token\": \"a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0u1v2w3x4y5z6a7b8c9d0e1f2\",\n  \"old_token_expiry\": \"2024-01-22T14:30:00Z\"\n}\n```\n","operationId":"rotateToken","tags":["Authentication"],"responses":{"200":{"description":"Token rotated successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RotateTokenResponse"}}}},"401":{"description":"Unauthorized - Invalid or expired token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden - User not authorized for this operation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}}}
````