> ## Documentation Index
> Fetch the complete documentation index at: https://docs.quidkey.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Authentication and Access

> Tokens, permissions and roles, and what each access failure answers

## Tokens

The API uses the OAuth 2.0 client credentials grant. Your credential is a `client_id` and a `client_secret`: a merchant finds them in the [Quidkey Console](https://console.quidkey.com), and a partner gets them from Quidkey.

1. Exchange them at `POST https://api.quidkey.com/v1/oauth2/token` with `grant_type=client_credentials`. Send a form-encoded body or JSON, with the credentials in the body or in HTTP Basic.
2. Send `Authorization: Bearer ACCESS_TOKEN` on every request. An endpoint that needs no token, such as `GET /agreements`, says so in its reference.
3. When the token expires, after `expires_in` seconds, exchange your credentials again. There's no refresh token.

[Getting started](https://docs.quidkey.com/api-v1/getting-started.md) shows each request. The token endpoint's response and errors follow OAuth 2.0, and aren't resource documents.

A token identifies the account that holds the credential, a partner or a merchant, and `GET /api-keys/current` tells a caller which. Creating, rotating and revoking credentials happens in Console or through Quidkey, not through the API. A token issued before its credential's secret was revoked or rotated stops working.

Credentials and tokens never go in a URL. The exception is a hosted link, a page a person opens, whose URL can carry a token. It's always an object with `url` and `expires_at`, and a hosted payment page is always called `checkout`. Treat a hosted link as a secret.

## Permissions and Roles

Every endpoint has one permission, named `resource:action`, such as `transactions:list` or `refunds:create`. `resource` is the plural name of what the permission gives access to, such as `transactions` for payment transactions. `action` is `list` on an endpoint answering a collection, `get` on one answering a single record, `create`, `update` or `delete`, or the name of the endpoint's own action, such as `refunds:execute`. A search takes its list's permission, so `POST /merchants/{id}/transactions:search` takes `transactions:list`. The one exception is `api-keys:get-current`, which `GET /api-keys/current` and `GET /api-keys/{id}` take: both only ever answer the credential that made the request, never another key, so the permission doesn't read as access to every key. Each endpoint's reference states it, with the credentials that can call the endpoint, a partner's, a merchant's or both. The OpenAPI document carries them too, as `x-permission` and `x-credentials`. A few endpoints on webhook endpoints take the owner's permission, and their reference names a partner's and a merchant's.

A role is a named set of permissions, held over a scope such as one merchant. A request succeeds when a role your credential holds covers the resource and contains the endpoint's permission.

| Credential | Role | What it can't do |
| - | - | - |
| A partner's | `partner:admin`, over the partner and its merchants | Read or manage a merchant's own webhook endpoints. A partner has its own endpoint. |
| A merchant's | `merchant:admin`, over the merchant | Start a party's identity check, or request a capability: both answer 403. Its partner does them. |

A role can gain permissions at any time. Removing a permission from a role comes with 6 months' notice, or sooner if security requires it.

## Access Failures

| Case | Answer |
| - | - |
| Missing, expired or invalid token | 401 `UNAUTHENTICATED` |
| Valid token, no permission for this endpoint | 403 `FORBIDDEN` |
| A resource outside your scope | 404 `NOT_FOUND`, exactly as if it didn't exist |
| A link to something you can't read | Fetching it answers 403 or 404 |

A 404 never confirms that something exists elsewhere. Anything whose existence is confidential sits in a sub-resource with its own permission.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.