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.

​
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

​
client_id
string
required
Your app’s client identifier from the developer portal.
​
redirect_uri
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.
​
scope
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.
​
response_type
string
required
Must be code.
​
code_challenge
string
required
The Base64URL-encoded SHA-256 hash of your app’s code_verifier.
​
code_challenge_method
string
required
Must be S256.
​
state
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:
  1. verify that state matches the value you originally sent
  2. extract the authorization code
  3. 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

​
grant_type
string
required
Must be authorization_code.
​
code
string
required
The authorization code returned to your redirect_uri.
​
redirect_uri
string
required
The same redirect_uri used in the authorization request.
​
client_id
string
required
Your app’s client identifier.
​
code_verifier
string
required
The original random secret generated by your app for this authorization request.
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"

​
Token response

A successful response returns OAuth tokens, including an access token and, when applicable, a refresh token.
​
access_token
string
The access token used to call COSMIC APIs.
​
token_type
string
The token type. Typically Bearer.
​
expires_in
integer
The lifetime of the access token in seconds.
​
refresh_token
string
A refresh token that can be used to obtain a new access token, when applicable.
​
scope
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

​
grant_type
string
required
Must be refresh_token.
​
refresh_token
string
required
The refresh token previously issued to your app.
​
client_id
string
Your app’s client identifier, if required by your app’s configured token endpoint authentication method.
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"

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