Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.natecosmic.com/llms.txt

Use this file to discover all available pages before exploring further.

Authorization is how COSMIC determines what a signed-in user, and the apps they authorize, can access and do. When a user authorizes an app through OAuth, that app acts on the user’s behalf within the scopes shown at consent and the access rules COSMIC enforces for that user and organization. In COSMIC, authorization is based on:
  • the authenticated user
  • the scopes granted on the access token for OAuth integrations (see Scopes)
  • the user’s membership, role, and org visibility in COSMIC

​
Authentication vs authorization

These terms are closely related, but they mean different things.
  • Authentication answers: who is this?
  • Authorization answers: what can they access or do?
For example:
  • When a user signs in to COSMIC, that is authentication
  • When COSMIC determines which organizations, members, certifications, or other resources that user can access, that is authorization
When an app calls the COSMIC API through OAuth, COSMIC still evaluates access in the context of the user who granted that app access.

​
What COSMIC checks

When COSMIC receives a request, it checks a few things.

​
The authenticated user

Every request is evaluated in the context of an authenticated user. Even when the request comes from an OAuth app, that app is acting on behalf of a specific user, not as a standalone actor with its own independent access.

​
Scopes on the token

For OAuth integrations, you choose which scopes the app may use when you configure the app in the developer portal. Users see that list at consent; when they approve, their access token carries the scopes they granted. See Scopes for the catalog and how sign-in scope on the authorize URL differs from API scopes (OAuth). Scopes limit what the app can do on the user’s behalf, but they do not replace the user’s own org membership or visibility in COSMIC. See Access tokens for inspecting scopes on a token and for listing organizations and members.

​
Org and member access

A valid token and the right scopes are not always enough. COSMIC also checks whether the user may access the target organization or member record (for example through membership or where an installed app is allowed to operate). That is why a request can include a valid access token and still return 403 or 404.

​
How authorization works in practice

A request must pass every relevant check. For example, COSMIC may verify that:
  • the user is authenticated
  • for OAuth app tokens, the token includes the scope required for that endpoint
  • the user may access the requested organization or member context
  • the action is allowed for that resource (for example not blocked until an org admin re-approves the app after you add or widen scopes in the developer portal)
If any of those checks fail, the request is denied. This is why having an access token is necessary, but not enough.

​
Authorization can change without a new token

Authorization is not fixed for the life of a token. Changes to things like:
  • organization membership
  • roles
  • org settings or access rules in COSMIC
can change what an existing token is allowed to access. A token may still be valid even though the user’s effective access has changed.
  • Access tokens — how tokens are sent with API requests
  • Scopes — what scopes represent and how they are granted
  • Apps — how OAuth apps are registered
  • OAuth — the end-to-end authorization flow
  • Quickstart — make your first authorized API request