> ## 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

> How COSMIC determines what a signed-in user, and the apps they authorize, can access and do.

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](/concepts/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{" "}
<a href="https://natecosmic.com/developers" rel="noopener noreferrer" target="_blank">developer portal</a>. Users see that list at consent; when they approve, their access token carries the scopes they granted. See [Scopes](/concepts/scopes) for the catalog and how sign-in `scope` on the authorize URL differs from API scopes ([OAuth](/guides/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](/concepts/access-token) 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.

## Related concepts

* [Access tokens](/concepts/access-token) — how tokens are sent with API requests
* [Scopes](/concepts/scopes) — what scopes represent and how they are granted
* [Apps](/concepts/apps) — how OAuth apps are registered
* [OAuth](/guides/oauth) — the end-to-end authorization flow
* [Quickstart](/quickstart) — make your first authorized API request
