Artemis supports two authentication methods for its API: password-based cookie sessions for browser clients and OAuth2 bearer tokens for programmatic access. This page explains both approaches, how to register an OAuth2 application, how to attach credentials to API requests, and what error responses to expect. For the complete OAuth2 authorization flow, including token exchange and refresh, see the OAuth2 guide.Documentation Index
Fetch the complete documentation index at: https://mintlify.com/artemis-development-group/artemis/llms.txt
Use this file to discover all available pages before exploring further.
Two authentication methods
Password / cookie sessions are handled automatically by the browser when a user logs in through the Artemis web interface (/api/v1/login). These sessions are cookie-based and are not suitable for third-party apps or scripts that operate outside the browser.
OAuth2 bearer tokens are the correct approach for any application that makes API calls on behalf of users or as itself. You obtain an access token through an OAuth2 flow, then include it in every request as an HTTP header.
All OAuth2 endpoints require HTTPS. Requests over plain HTTP will be rejected.
Registering an OAuth2 application
Before you can request tokens you must register an application in the Artemis preferences.Create a new app
Click create another app and fill in:
- Name — a display name for your application.
- App type — choose the type that matches your use case (see below).
- Description — an optional human-readable description.
- Redirect URI — the URI Artemis will redirect users back to after authorization. Must be an exact match at token-exchange time.
App types
| Type | Use case |
|---|---|
| web app | Confidential client running on a server. Has a client secret. Supports authorization code and client credentials flows. |
| installed app | Non-confidential client distributed to end users (desktop or mobile). Uses the installed client extension grant. |
| script | Personal-use or bot scripts. Supports the password grant; the developer’s own account credentials are used directly. |
Supported OAuth2 flows
- Password grant (script apps)
- Client credentials (server-to-server)
Using bearer tokens in requests
Once you have an access token, include it in theAuthorization header on every API request:
Example
Base URL
All API requests go to your self-hosted Artemis instance. Replace the hostname in every example with your own:Common authentication errors
| Status | Meaning |
|---|---|
401 Unauthorized | No credentials were provided, or the provided token is invalid or expired. Check that the Authorization: Bearer header is present and the token has not been revoked. |
403 Forbidden | Credentials are valid but the token lacks the required OAuth2 scope for the endpoint you are calling. Request a new token with the appropriate scopes. |
OAuth2 error responses
When an OAuth2 flow itself fails (for example, during token exchange), the API returns a JSON body with anerror field:
| Error | Cause |
|---|---|
invalid_grant | Authorization code or refresh token is invalid, expired, or already used. |
invalid_scope | One or more requested scopes are not recognized. |
unauthorized_client | The app type is not permitted to use the requested grant type. |
unsupported_grant_type | The grant_type value is not one of the supported options. |
access_denied | The user declined the authorization request. |
Rate limiting
Artemis enforces IP-based rate limits on authentication endpoints including/api/v1/access_token and /api/v1/revoke_token. Exceeding the limit returns a 429 Too Many Requests response. Back off and retry after a delay before making further requests.
Next steps
- Read the OAuth2 guide for the full authorization code flow, token exchange details, scope reference, and curl examples for every step.