Authentication

Every call except GET /auth/auth_details, which is public, carries a bearer token in the Authorization header. For a system-to-system integration (an HR system, an LMS, identity tooling), that token is an access key.

The single sign-on endpoints do not take an access key: the Retorio coaching app calls POST /auth/coaching_sso_signup with the coaching user’s own Retorio sign-in token, issued once they sign in through your identity provider.

Create a key

1. An Owner, or an admin whose role allows managing access keys, opens Integrations under Organization in the Retorio admin app’s sidebar and selects Create access key.
2. Name the key after the system that will use it, so other admins know what revoking it affects. Each key that has not been revoked needs its own name.
3. Choose an expiry: 30, 90 or 180 days, 1 year, or a date of your own, at most one year ahead. Every key you create expires.
4. Copy the key from the dialog. It is shown only this once: it cannot be retrieved through the admin app or the API afterwards. Retorio keeps only a fingerprint of it, so if you lose a key, revoke it and create a new one.
5. Hand it to the system that calls the API through a secrets manager or password manager, never email or chat.

Send it

curl https://api.retorio.com/be/v2/cohorts \
  -H "Authorization: Bearer $RETORIO_ACCESS_KEY"

What a key can do

Treat the key as a full administrative credential for your organization. It acts with the permissions of the admin who created it, and only ever reads or changes your organization’s data. Store it in a secrets manager, never in source code or a browser, and give it only to the systems that call the API.

Rule	Consequence
A key belongs to the admin who created it	When that admin is removed from your organization, every key they created stops working, and its calls get 401 with a message saying so. Changing that admin’s roles changes what the key can do from its next request
Roles decide which calls work	The Owner role covers every cohort and webhook call. The Admin role covers the cohort calls but not webhooks, which need the Owner role or a role that allows managing webhooks. Every endpoint’s roles: Roles and permissions
Some calls are never open to a key	A key cannot manage access keys, invite or remove admins, or change roles. Those calls answer 403 whatever its admin holds

Create keys from an account that will outlive any one person, such as a dedicated integration admin, with roles that cover the calls your integration makes. That account creates its own keys, so it also needs to be an Owner or hold a role that allows managing access keys.

Each key’s Details on the Integrations page show when it was first and last used, and how many calls it has made.

Expiry, revocation and rotation

Event	What happens
Expiry	A key you create works until the end of the expiry date you chose, in UTC. The Integrations page shows each key’s exact cutoff in your browser’s time zone. After that every call gets 401
Revocation	An admin allowed to manage access keys revokes the key on the Integrations page. It stops working from the next request. Revoked keys stay listed under Show revoked
Rotation	Create a new key before the old one expires, move your systems over to it, then revoke the old one

Keys your organization created before access keys were managed in the admin app appear in the list as legacy keys. They stop at the date and time shown, so replace them the same way before then.