Astral API Docs

Astral implements the OAuth2 authorization code flow so third-party applications can act on behalf of Astral users with granular permissions.

Overview

Your app redirects the user to Astral's authorization page.
The user approves (or denies) your requested scopes.
Astral redirects back to your app with an authorization code.
Your server exchanges the code for an access token and refresh token.
You use the access token to call the API as that user.

Registering an Application

Open the Astral client at astraof.com.
Go to User Settings → Applications.
Click Create Application.
Fill in the name and redirect URI(s).
Copy the Client ID and Client Secret.

Keep your client secret safe

Never expose the client secret in frontend code, mobile apps, or public repositories. It is used only server-side.

Authorization URL

Redirect users to:

https://astraof.com/oauth2/authorize?client_id=YOUR_CLIENT_ID&redirect_uri=YOUR_REDIRECT_URI&response_type=code&scope=identify+guilds

Query Parameters

Parameter	Required	Description
client_id	yes	Your application's client ID
redirect_uri	yes	One of your registered redirect URIs
response_type	yes	Must be `code`
scope	yes	Space-delimited list of scopes
state	recommended	Random string to prevent CSRF; returned unchanged in the callback

Scopes

Scope	Description
`identify`	Read the user's ID, username, avatar, and discriminator
`email`	Read the user's email address
`guilds`	List guilds the user is in
`guilds.join`	Join guilds on behalf of the user
`bot`	Add a bot to a guild (used in the bot authorization flow)
`connections`	Read the user's linked accounts
`messages.read`	Read messages in channels the user can access

Token Exchange

After the user approves, Astral redirects to your redirect URI with a code parameter. Exchange it:

POST /api/v1/oauth2/token
Content-Type: application/x-www-form-urlencoded

grant_type=authorization_code&code=THE_CODE&redirect_uri=YOUR_REDIRECT_URI&client_id=YOUR_CLIENT_ID&client_secret=YOUR_CLIENT_SECRET

Response:

{
  "access_token": "eyJ...",
  "token_type": "Bearer",
  "expires_in": 604800,
  "refresh_token": "abc123...",
  "scope": "identify guilds"
}

Refreshing Tokens

Access tokens expire after 7 days. Use the refresh token to get a new one:

POST /api/v1/oauth2/token
Content-Type: application/x-www-form-urlencoded

grant_type=refresh_token&refresh_token=YOUR_REFRESH_TOKEN&client_id=YOUR_CLIENT_ID&client_secret=YOUR_CLIENT_SECRET

Using the Token

Authorization: Bearer YOUR_ACCESS_TOKEN

The Bearer prefix (not Bot) tells the API this is a user token from OAuth2.

Get Current User

GET /api/v1/users/@me
Authorization: Bearer YOUR_ACCESS_TOKEN

Requires the identify scope.

Get User Guilds

GET /api/v1/users/@me/guilds
Authorization: Bearer YOUR_ACCESS_TOKEN

Requires the guilds scope.

Revoking Tokens

POST /api/v1/oauth2/token/revoke
Content-Type: application/x-www-form-urlencoded

token=YOUR_TOKEN&client_id=YOUR_CLIENT_ID&client_secret=YOUR_CLIENT_SECRET

Bot Authorization Flow

To add a bot to a guild, redirect the guild administrator to:

https://astraof.com/oauth2/authorize?client_id=YOUR_CLIENT_ID&scope=bot&permissions=PERMISSION_INTEGER

The permissions parameter specifies default permissions as a bitfield integer. See Permissions for the full list.

Security Recommendations

Always validate the state parameter on the callback to prevent CSRF attacks.
Store tokens server-side — never expose access tokens to the browser.
Request only the scopes you need — users are more likely to approve minimal permission requests.
Handle token expiry gracefully — check for 401 responses and refresh transparently.
Revoke tokens when users disconnect your integration to respect their privacy.

OAuth2

On this page