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

# Scopes

> How you select scopes for your app and how COSMIC enforces them on API requests.

**Scopes** are the access levels your app needs when calling the COSMIC API. You select them per app in the{" "}
<a href="https://natecosmic.com/developers" rel="noopener noreferrer" target="_blank">developer portal</a>; users see the same list at consent before they approve your app.

Scopes are separate from the **`scope`** query parameter on the OAuth authorize URL (used for sign-in and basic profile, for example `openid`, `email`, `profile`) — see [OAuth](/guides/oauth).

## How scopes are used

1. You enable the scopes your app needs in the developer portal.
2. The consent screen shows those scopes to the user when they authorize your app.
3. The COSMIC API enforces them on every request.
4. `GET /v1/me` returns the scopes granted to the current token.

## Scope reference

| Category       | Scope                         | Typical use                                               |
| -------------- | ----------------------------- | --------------------------------------------------------- |
| Organizations  | `organizations:read`          | List and read organizations the principal may access      |
| Organizations  | `organizations:write`         | Update organization profile data where the API allows it  |
| Organizations  | `organization_members:read`   | Read organization membership records                      |
| Organizations  | `organization_members:write`  | Create, update, or remove organization membership records |
| Certifications | `certification_records:read`  | Read certification records                                |
| Certifications | `certification_records:write` | Create or update certification records                    |
| Definitions    | `certification_types:read`    | Read certification type definitions                       |
| Definitions    | `certification_types:write`   | Create or update organization certification types         |
| Definitions    | `job_roles:read`              | Read job roles and assignments                            |
| Definitions    | `job_roles:write`             | Create or update organization job roles                   |
| Definitions    | `qualifications:read`         | Read qualification definitions                            |
| Definitions    | `qualifications:write`        | Create or update organization qualifications              |

<Note>
  Some operations in the [API reference](/api-reference/api) include scope notes in their descriptions; this page lists the full catalog.
</Note>

## Choosing scopes

* Enable only the scopes your integration needs in the developer portal.
* Prefer read scopes first; add write scopes only where you create or update data.
* If you ship new features later, enable the corresponding scopes in the developer portal rather than enabling broad access up front.

## Related

* [Apps](/concepts/apps)
* [Access tokens](/concepts/access-token)
* [OAuth](/guides/oauth)
* [Creating apps](/guides/creating-apps)