OAuth2 authorization flow and token management

Artemis implements OAuth 2.0 for delegated API access. This page walks through every step of the OAuth2 lifecycle from a client perspective: registering an application, sending users through the authorization flow, exchanging the authorization code for access and refresh tokens, keeping tokens fresh, and revoking them when they are no longer needed. Script and personal-use app flows using the password grant are also covered. For a high-level comparison of the available flows, see the authentication overview.

Registering your application

All OAuth2 clients must be registered at /prefs/apps before they can request tokens.

Field	Description
Name	Display name shown to users during the authorization prompt.
App type	`web app` (confidential, server-side), `installed app` (non-confidential, distributed), or `script` (personal use / bots).
Description	Optional. Displayed to users on the authorization screen.
Redirect URI	The URI Artemis redirects users to after they approve or deny access. Must exactly match the `redirect_uri` you send in every authorization request.

After saving you receive a client ID and, for confidential clients, a client secret. Keep the secret private and never expose it in client-side code.

OAuth2 scopes

Scopes define what parts of the API an access token is permitted to use. You request scopes as a space-separated string during authorization.

Scope	Name	What it grants
`identity`	My Identity	Read the authenticated user’s username and signup date.
`account`	Update account information	Update preferences and account information (not email or password).
`read`	Read Content	Access posts and comments through the user’s account.
`submit`	Submit Content	Submit links and comments from the user’s account.
`edit`	Edit Posts	Edit and delete the user’s comments and submissions.
`vote`	Vote	Submit and change votes on comments and submissions.
`save`	Save Content	Save and unsave comments and submissions.
`history`	History	Access voting history, saved, and hidden content.
`report`	Report content	Report content for rules violations. Hide and show individual submissions.
`subscribe`	Edit My Subscriptions	Manage branch subscriptions and the friends list.
`mybranches`	My Branches	Access the list of branches the user moderates, contributes to, and subscribes to.
`flair`	Manage My Flair	Select branch flair and change link flair on submissions.
`privatemessages`	Private Messages	Access the inbox and send private messages.
`cbranches`	Spend artemis gold cbranches	Spend gold cbranches to give gold to other users.
`modconfig`	Moderate Branch Configuration	Manage configuration, sidebar, and CSS of moderated branches.
`modcontributors`	Approve submitters and ban users	Add or remove approved submitters; ban, unban, mute, and unmute users.
`modflair`	Moderate Flair	Manage and assign flair in moderated branches.
`modlog`	Moderation Log	Access the moderation log in moderated branches.
`modothers`	Invite or remove other moderators	Invite or remove moderators from moderated branches.
`modposts`	Moderate Posts	Approve, remove, mark NSFW, and distinguish content in moderated branches.
`modself`	Moderator and contributor status	Accept moderator invitations; remove self as moderator or contributor.
`modtraffic`	Branch Traffic	Access traffic stats in moderated branches.
`modwiki`	Moderate Wiki	Change wiki page editors and visibility in moderated branches.
`wikiedit`	Wiki Editing	Edit wiki pages on the user’s behalf.
`wikiread`	Read Wiki Pages	Read wiki pages through the user’s account.

Script apps (password grant) receive the * full-access scope by default if no explicit scope is requested.

You can query the live scope list at any time:

GET /api/v1/scopes

Pass a comma or space-separated list of scope names in the scopes query parameter to filter the response to specific scopes.

Authorization code flow

Use this flow for web and installed applications that act on behalf of other Artemis users.

Redirect the user to /api/v1/authorize

Send the user’s browser to the authorization endpoint with the following query parameters:

query.client_id

string

required

Your application’s client ID from /prefs/apps.

query.response_type

string

required

Must be code for the authorization code flow, or token for the implicit flow (non-confidential installed apps only; does not issue refresh tokens).

query.state

string

required

An opaque value you generate to maintain state between the request and callback. Artemis returns this value unchanged in the redirect. Use it to prevent CSRF attacks.

query.redirect_uri

string

required

Must exactly match the redirect URI registered for your application.

query.scope

string

required

Space-separated list of scopes to request. See the scope table above.

query.duration

string

default:"temporary"

temporary for a short-lived access token only. permanent to also receive a refresh token that can be used to obtain new access tokens without re-authorization.

GET https://<your-artemis-instance>/api/v1/authorize
  ?client_id=YOUR_CLIENT_ID
  &response_type=code
  &state=RANDOM_STATE_VALUE
  &redirect_uri=https://yourapp.example.com/callback
  &scope=identity%20read%20submit
  &duration=permanent

Artemis displays an authorization page where the user can approve or deny your request.

Handle the redirect callback

If the user approves, Artemis redirects to your redirect_uri with the following query parameters appended:

code — a short-lived, single-use authorization code.
state — the exact value you passed in step 1.

Verify that state matches the value you originally sent, then proceed to exchange the code.If the user denies the request, the redirect instead contains error=access_denied and the state value.

Exchange the code for tokens

Make a server-side POST request to /api/v1/access_token. The request must use HTTP Basic authentication with your client ID as the username and client secret as the password.

body.grant_type

string

required

Must be authorization_code.

body.code

string

required

The authorization code received in the redirect callback.

body.redirect_uri

string

required

Must exactly match the redirect_uri used in the authorization request.

curl -X POST https://<your-artemis-instance>/api/v1/access_token \
  -u "YOUR_CLIENT_ID:YOUR_CLIENT_SECRET" \
  -d "grant_type=authorization_code" \
  -d "code=AUTHORIZATION_CODE" \
  -d "redirect_uri=https://yourapp.example.com/callback"

A successful response:

{
  "access_token": "eyJhbGciOiJSUzI1NiJ9...",
  "token_type": "bearer",
  "expires_in": 3600,
  "scope": "identity read submit",
  "refresh_token": "eyJhbGciOiJSUzI1NiJ9..."
}

refresh_token is only present when duration=permanent was requested.

Token response fields

access_token

string

required

The bearer token to include in API requests.

token_type

string

required

Always bearer.

expires_in

number

required

Seconds until the access token expires. Typically 3600 (one hour).

scope

string

required

Space-separated list of scopes granted to this token.

refresh_token

string

Present only on permanent grants. Use this to obtain new access tokens without re-authorization.

Refreshing an access token

When an access token expires, use the refresh token to obtain a new one without sending the user through the authorization flow again.

body.grant_type

string

required

Must be refresh_token.

body.refresh_token

string

required

The refresh token returned during the initial token exchange.

curl -X POST https://<your-artemis-instance>/api/v1/access_token \
  -u "YOUR_CLIENT_ID:YOUR_CLIENT_SECRET" \
  -d "grant_type=refresh_token" \
  -d "refresh_token=YOUR_REFRESH_TOKEN"

A successful response returns a new access_token and expires_in. The refresh token itself remains valid and can be reused for subsequent refreshes.

{
  "access_token": "eyJhbGciOiJSUzI1NiJ9...",
  "token_type": "bearer",
  "expires_in": 3600,
  "scope": "identity read submit"
}

If the refresh token is invalid, expired, or was issued to a different client, the response is 400 Bad Request with "error": "invalid_grant". In this case the user must re-authorize your application.

Revoking tokens

Revoke an access or refresh token when the user disconnects your application or when you no longer need the token. Revoking a refresh token does not automatically revoke existing access tokens derived from it.

body.token

string

required

The token string to revoke (access token or refresh token).

body.token_type_hint

string

Optional hint to help the server locate the token faster. One of access_token or refresh_token.

curl -X POST https://<your-artemis-instance>/api/v1/revoke_token \
  -u "YOUR_CLIENT_ID:YOUR_CLIENT_SECRET" \
  -d "token=TOKEN_TO_REVOKE" \
  -d "token_type_hint=access_token"

A successful revocation returns 204 No Content with an empty body. The endpoint also returns 204 if the token does not exist or has already been revoked — the outcome (the token is no longer valid) is the same either way.

Script / personal-use apps (password grant)

If your app type is script and you are authenticating as one of the app’s registered developers, you can exchange credentials directly for a token without any browser redirect.

body.grant_type

string

required

Must be password.

body.username

string

required

Your Artemis username.

body.password

string

required

Your Artemis password.

body.scope

string

Space-separated list of scopes. If omitted, the token receives full access (*).

curl -X POST https://<your-artemis-instance>/api/v1/access_token \
  -u "YOUR_CLIENT_ID:YOUR_CLIENT_SECRET" \
  -d "grant_type=password" \
  -d "username=YOUR_USERNAME" \
  -d "password=YOUR_PASSWORD"

{
  "access_token": "eyJhbGciOiJSUzI1NiJ9...",
  "token_type": "bearer",
  "expires_in": 3600,
  "scope": "*"
}

The password grant is restricted to script app types only. The authenticated user must be a registered developer of the application. Any other configuration returns "error": "unauthorized_client".

Using bearer tokens in API requests

Include the access token in the Authorization header on every authenticated API call:

curl -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
     https://<your-artemis-instance>/api/v1/me

curl
Python
JavaScript

curl https://<your-artemis-instance>/api/v1/me \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

import requests

headers = {"Authorization": "Bearer YOUR_ACCESS_TOKEN"}
response = requests.get(
    "https://<your-artemis-instance>/api/v1/me",
    headers=headers,
)
print(response.json())

const response = await fetch("https://<your-artemis-instance>/api/v1/me", {
  headers: {
    Authorization: "Bearer YOUR_ACCESS_TOKEN",
  },
});
const data = await response.json();

A 403 Forbidden response means the token is valid but lacks the scope required by the endpoint. Request a new token with the necessary scopes.

Endpoint reference

Endpoint	Method	Description
`/api/v1/authorize`	`GET`	Display the authorization consent page to the user.
`/api/v1/access_token`	`POST`	Exchange an authorization code, refresh token, or credentials for an access token.
`/api/v1/revoke_token`	`POST`	Revoke an access or refresh token.
`/api/v1/scopes`	`GET`	List available OAuth2 scopes and their descriptions.

Authentication

Endpoints

Developer Guide

OAuth2 authorization flow and token management

Registering your application

OAuth2 scopes

Authorization code flow

Token response fields

Refreshing an access token

Revoking tokens

Script / personal-use apps (password grant)

Using bearer tokens in API requests

Endpoint reference

Build docs developers (and LLMs) love

Authentication

Endpoints

Developer Guide

Documentation Index

​Registering your application

​OAuth2 scopes

​Authorization code flow

​Token response fields

​Refreshing an access token

​Revoking tokens

​Script / personal-use apps (password grant)

​Using bearer tokens in API requests

​Endpoint reference

Build docs developers (and LLMs) love

Registering your application

OAuth2 scopes

Authorization code flow

Token response fields

Refreshing an access token

Revoking tokens

Script / personal-use apps (password grant)

Using bearer tokens in API requests

Endpoint reference