OAuth

Overview

COSMIC supports OAuth 2.1 Authorization Code with PKCE. Most integrations follow this flow:

Before you begin

Create an app in the developer portal. You will need your app’s client_id, at least one allowed redirect_uri, and the scopes your app will use. See Creating apps.

Authorization endpoint

Start the OAuth flow by redirecting the user to:

GET https://api.natecosmic.com/auth/v1/oauth/authorize?
  response_type=code
  &client_id=YOUR_CLIENT_ID
  &redirect_uri=https%3A%2F%2Fyour-app.com%2Foauth%2Fcallback
  &code_challenge=YOUR_CODE_CHALLENGE
  &code_challenge_method=S256
  &state=RANDOM_STATE

Optional: append &scope=openid%20email%20profile if you need broader sign-in profile data or an ID token—see scope below.

Query parameters

string

required

Your app’s client identifier from the developer portal.

string

required

The callback URI to redirect the user to after authorization. This must exactly match one of the allowed redirect URIs configured for your app.

Redirect URIs must match exactly, including scheme, host, path, and trailing slash. See Redirect URIs.

string

Optional. Space-separated OpenID Connect / OAuth sign-in values for this step only (for example openid email profile). They do not select COSMIC API permissions—those come from your app in the developer portal; see Scopes. If you omit scope, COSMIC uses a default suitable for basic sign-in; include openid when you need an ID token in the token response.

string

required

Must be code.

string

required

The Base64URL-encoded SHA-256 hash of your app’s code_verifier.

string

required

Must be S256.

string

A client-generated value used to prevent CSRF. Generate a unique value per request and verify it on callback.

See Scopes for guidance on selecting scopes. After the user signs in and approves the request, COSMIC redirects the browser to your registered redirect_uri. Example:

https://your-app.com/oauth/callback?code=AUTHORIZATION_CODE&state=RANDOM_STATE

Your app should:

verify that state matches the value you originally sent
extract the authorization code
exchange that code at the token endpoint

See Authorization for the consent flow details and Redirect URIs for callback registration and matching rules.

Token endpoint

Exchange the authorization code at:

POST https://api.natecosmic.com/auth/v1/oauth/token

Authorization code exchange parameters

string

required

Must be authorization_code.

string

required

The authorization code returned to your redirect_uri.

string

required

The same redirect_uri used in the authorization request.

string

required

Your app’s client identifier.

string

required

The original random secret generated by your app for this authorization request.

Public client
Confidential client

Send the token request without a client_secret.

curl -X POST https://api.natecosmic.com/auth/v1/oauth/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=authorization_code" \
  -d "code=AUTHORIZATION_CODE" \
  -d "redirect_uri=https://your-app.com/oauth/callback" \
  -d "client_id=YOUR_CLIENT_ID" \
  -d "code_verifier=YOUR_CODE_VERIFIER"

Send the token request using the authentication method configured for your app in the developer portal.

curl -X POST https://api.natecosmic.com/auth/v1/oauth/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -u "YOUR_CLIENT_ID:YOUR_CLIENT_SECRET" \
  -d "grant_type=authorization_code" \
  -d "code=AUTHORIZATION_CODE" \
  -d "redirect_uri=https://your-app.com/oauth/callback" \
  -d "code_verifier=YOUR_CODE_VERIFIER"

This example uses HTTP Basic authentication for the client credentials. If your app is configured differently, send the client credentials using that method instead.

Token response

A successful response returns OAuth tokens, including an access token and, when applicable, a refresh token.

string

The access token used to call COSMIC APIs.

string

The token type. Typically Bearer.

integer

The lifetime of the access token in seconds.

string

A refresh token that can be used to obtain a new access token, when applicable.

string

Space-delimited sign-in / identity scopes for this authorization (from your authorize request, or COSMIC defaults). This is separate from COSMIC API scopes on the token; see Scopes and Access tokens.

Use the access token as a Bearer token when calling COSMIC APIs.

After you receive a token

Use the access token as a Bearer credential on API requests. See Access tokens for GET /v1/me, scopes on the token, and how to list organizations and members. If a call returns 403, common causes include:

the token does not include the scope required for that endpoint
the app cannot access that organization or member in the current context
an organization admin must re-approve the app in COSMIC after you add or widen scopes in the developer portal

See Authorization and Scopes.

Refresh tokens

To obtain a new access token, send a refresh token to the same token endpoint:

POST https://api.natecosmic.com/auth/v1/oauth/token

Refresh token parameters

string

required

Must be refresh_token.

string

required

The refresh token previously issued to your app.

string

Your app’s client identifier, if required by your app’s configured token endpoint authentication method.

Public client
Confidential client

Send the refresh token request without a client_secret.

curl -X POST https://api.natecosmic.com/auth/v1/oauth/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=refresh_token" \
  -d "refresh_token=YOUR_REFRESH_TOKEN" \
  -d "client_id=YOUR_CLIENT_ID"

Send the refresh token request using the authentication method configured for your app in the developer portal.

curl -X POST https://api.natecosmic.com/auth/v1/oauth/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -u "YOUR_CLIENT_ID:YOUR_CLIENT_SECRET" \
  -d "grant_type=refresh_token" \
  -d "refresh_token=YOUR_REFRESH_TOKEN"

This example uses HTTP Basic authentication for the client credentials. If your app is configured differently, send the client credentials using that method instead.

Common errors

`redirect_uri` mismatch

The redirect_uri sent in the authorization request and token request must exactly match a URI registered for the client. This includes:

scheme
host
path
trailing slash

See Redirect URIs.

`invalid_grant`

Common causes include:

the authorization code expired
the authorization code was already used
the code_verifier does not match the original PKCE challenge
the redirect_uri does not match the original authorization request

`state` mismatch

If you send state, verify it on callback. Reject the response if the returned value does not match the original value stored by your app.

Get Started

Concepts

Guides

API reference

Overview

Before you begin

Authorization endpoint

Query parameters

Token endpoint

Authorization code exchange parameters

Token response

After you receive a token

Refresh tokens

Refresh token parameters

Common errors

`redirect_uri` mismatch

`invalid_grant`

`state` mismatch

​Overview

​Before you begin

​Authorization endpoint

​Query parameters

​User consent and redirect

​Token endpoint

​Authorization code exchange parameters

​Token response

​After you receive a token

​Refresh tokens

​Refresh token parameters

​Common errors

​redirect_uri mismatch

​invalid_grant

​state mismatch

​Related guides

Overview

Before you begin

Authorization endpoint

Query parameters

User consent and redirect

Token endpoint

Authorization code exchange parameters

Token response

After you receive a token

Refresh tokens

Refresh token parameters

Common errors

`redirect_uri` mismatch

`invalid_grant`

`state` mismatch

Related guides