Authentication and organizations
The API accepts user API keys and OAuth 2.0 access tokens as bearer credentials. Both identify an authorized user. Trutee resolves an exact organization, verifies that user’s current membership, and derives capabilities from the membership role on every request.
Choose an authentication method
Use a user API key for scripts, server-to-server jobs, and integrations operated directly by one Trutee user. Use OAuth when your product needs an end user to authorize a client and select an organization through a consent flow.
Do not use organization API keys when individual user attribution is required. A shared organization credential cannot reliably identify which person performed an action.
User API keys
Create a user API key from your Trutee user profile and copy it immediately. Store it in a server-side secret store; never place it in browser or mobile application code, source control, logs, URLs, or analytics.
Send the key as a bearer credential and identify the organization using the slug shown under Dashboard → Organization Settings → General:
The API key subject is the acting user. Trutee-Organization selects context but never grants access: Trutee verifies that the same user is still a member of that exact organization and fails closed if the slug, membership, or role is invalid. Changing organizations requires changing the header and rediscovering all opaque IDs and cursors.
User API keys are long-lived until they expire or are revoked. Give each integration its own descriptively named key, keep it in a secret manager, and revoke it immediately if it may have been exposed. A revoked or expired key returns 401 unauthorized.
OAuth onboarding and token flow
- Request Public API access. Include your company and technical contact, the organization that needs access, intended use case, production HTTPS redirect URI or URIs, and whether you need a course-approved test Tee Time. Trutee provisions the production integration and supplies the OAuth client ID, client secret, authorization endpoint, token endpoint, and issuer/resource metadata; client credentials and access tokens must stay in your secret store.
- Redirect the authorized user to the supplied authorization endpoint with your client ID, an exact registered redirect URI, and a cryptographically random
state. The user signs in and selects the approved organization during consent. Reject callbacks whosestatedoes not match. - Exchange the returned authorization code at the supplied token endpoint from your server. Never exchange codes or store client credentials in browser or mobile application code.
- Send the access token as
Authorization: Bearer <token>. The selected organization is part of the resolved OAuth context; it is not a request parameter or caller-asserted header. - Renew tokens through the OAuth flow and metadata Trutee supplies. When renewal is unavailable, consent is revoked, the user changes organization, or the API returns an organization/authentication error, restart authorization and require organization selection again. Rediscover IDs after changing organizations.
Provisioning handoff
Do not begin implementation until Trutee has supplied all of these values:
OAuth profile
The first Public API integration uses this OAuth profile unless Trutee explicitly provisions different values:
Do not use the Client Credentials grant. Every API token must continue to represent an authorizing user and the selected Integration Organization, including background reconciliation jobs.
Build the authorization redirect from the supplied endpoint using response_type=code, your client ID, exact redirect URI, and a cryptographically random state. Preserve any additional parameters supplied by Trutee. After validating the callback’s state, exchange the code from your server:
For example, the browser redirect has this shape; the endpoint and values shown are placeholders:
The authorization server redirects back with code and the same state:
The callback can instead contain error, optional error_description, and the original state. Always validate and consume state before handling either outcome. Treat access_denied as a user cancellation, show a restart option, and do not exchange a code when any OAuth error is present. Reject callbacks containing both code and error, a missing or reused state, or a redirect URI that does not reach the exact registered server route.
Create the authorization URL and persist the state in an encrypted or signed server-side session before redirecting:
At the callback, compare state using your framework’s timing-safe session mechanism, consume it once, reject OAuth errors, and exchange the code only from your server. The token request is:
A successful token response has this general shape. Exact fields and lifetimes come from the provisioning metadata:
Token endpoint failures use the OAuth JSON error shape:
Handle the common cases deliberately:
Use expires_in to calculate expiry with a small clock-skew allowance. Refresh before starting work that may outlive the access token. If refresh returns a replacement refresh token, atomically replace the stored token only after the new token set is safely persisted; never log either token.
Persist the returned refresh token in your secret store. Background reconciliation still acts for the authorizing user and selected organization; a client-credentials-only token is not supported. Refresh without sending a user through consent again:
Treat the exact endpoints, parameters, token lifetime, and renewal metadata supplied during provisioning as authoritative. Never log API keys, authorization codes, client secrets, access tokens, or refresh tokens.
Trutee manages OAuth client registration and redirect allowlisting. This API documentation does not expose or ask you to configure Trutee deployment secrets, preview credentials, or private-beta runtime settings.
The dated contract derives capabilities from the verified membership assigned during onboarding. Internal role names are not part of the public contract:
An unknown role returns unsupported_organization_role; it never inherits access. Missing OAuth organization context or a missing API-key Trutee-Organization header returns organization_required. A mismatched or missing membership returns forbidden.
The dated API derives authorization from the resolved organization and verified membership role; it does not treat unavailable custom credential scopes as an authorization boundary.
Authorization is always rechecked against the resolved principal. Availability offers and availability cursors are cryptographically principal-bound; Reservation-list cursors are filter- and page-size-bound and remain authorization-scoped when used. Opaque resource IDs are encrypted type-safe references, not bearer credentials. Switching the selected organization requires rediscovery; never treat an ID or cursor as proof of access or reuse it across organizations.

