Tokens
The API uses the OAuth 2.0 client credentials grant. Your credential is aclient_id and a client_secret: a merchant finds them in the Quidkey Console, and a partner gets them from Quidkey.
- Exchange them at
POST https://api.quidkey.com/v1/oauth2/tokenwithgrant_type=client_credentials. Send a form-encoded body or JSON, with the credentials in the body or in HTTP Basic. - Send
Authorization: Bearer ACCESS_TOKENon every request. An endpoint that needs no token, such asGET /agreements, says so in its reference. - When the token expires, after
expires_inseconds, exchange your credentials again. There’s no refresh token.
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, namedresource: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.
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
A 404 never confirms that something exists elsewhere. Anything whose existence is confidential sits in a sub-resource with its own permission.