REST API authentication

Authenticate Redmine API requests using an API key, HTTP Basic Auth, or OAuth2 via Doorkeeper.

Redmine supports three authentication methods for the REST API. All API requests must use one of these methods — unauthenticated requests will return 401 Unauthorized.

The REST API must be enabled in Administration → Settings → API before any authentication method will work.

API key authentication

The recommended method for server-to-server integrations. Each Redmine user has a personal API key that can be used instead of a password.

Getting your API key

1. Log in to Redmine

   Navigate to your Redmine instance and sign in with your credentials.

2. Open My Account

   Click your username in the top-right corner and select My account.

3. Reveal your API key

   Scroll to the bottom-right of the page and click Show next to API access key. You can also generate a new key by clicking Reset.

Using the API key

You can pass the API key in two ways.

As an HTTP header (recommended):

curl -H "X-Redmine-API-Key: YOUR_API_KEY" \
  https://redmine.example.com/issues.json

As a query parameter:

curl "https://redmine.example.com/issues.json?key=YOUR_API_KEY"

Prefer the header method. Query parameters can appear in server access logs.

HTTP Basic Auth

You can authenticate with your Redmine username and password using HTTP Basic Auth. This is convenient for quick testing.

curl -u username:password \
  https://redmine.example.com/issues.json

You can also use your API key as the password with any username:

curl -u username:YOUR_API_KEY \
  https://redmine.example.com/issues.json

HTTP Basic Auth transmits credentials with every request. Always use HTTPS when using Basic Auth. Users with two-factor authentication (2FA) enabled cannot use username/password Basic Auth — they must use their API key instead.

OAuth2 (Doorkeeper)

Redmine includes the Doorkeeper gem, which provides a full OAuth2 authorization server. Use OAuth2 when building third-party applications that act on behalf of Redmine users.

OAuth2 endpoints

Endpoint	Path
Authorization	GET /oauth/authorize
Token	POST /oauth/token
Token info	GET /oauth/token/info
Revoke token	POST /oauth/revoke

Registering an application

An administrator must register your application before you can use OAuth2.

1. Open the OAuth applications page

   Navigate to Administration → OAuth applications (available to administrators).

2. Create a new application

   Click New application and fill in the name and redirect URI for your application.

3. Copy your credentials

   After saving, copy the Application ID (client ID) and Secret (client secret).

Authorization code flow

1. Redirect the user to the authorization endpoint

   GET /oauth/authorize
     ?client_id=YOUR_CLIENT_ID
     &redirect_uri=https://yourapp.example.com/callback
     &response_type=code
   
2. Exchange the code for a token

   After the user approves access, Redmine redirects to your redirect_uri with a code parameter. Exchange it for an access token:

   curl -X POST https://redmine.example.com/oauth/token \
     -d "client_id=YOUR_CLIENT_ID" \
     -d "client_secret=YOUR_CLIENT_SECRET" \
     -d "code=AUTHORIZATION_CODE" \
     -d "grant_type=authorization_code" \
     -d "redirect_uri=https://yourapp.example.com/callback"
   

   Response:

   {
     "access_token": "abc123...",
     "token_type": "Bearer",
     "expires_in": 7200,
     "refresh_token": "xyz789...",
     "scope": "api",
     "created_at": 1711000000
   }
   
3. Use the access token

   Include the token in the Authorization header:

   curl -H "Authorization: Bearer abc123..." \
     https://redmine.example.com/issues.json
   

Refreshing a token

curl -X POST https://redmine.example.com/oauth/token \
  -d "client_id=YOUR_CLIENT_ID" \
  -d "client_secret=YOUR_CLIENT_SECRET" \
  -d "refresh_token=xyz789..." \
  -d "grant_type=refresh_token"

Admin: impersonating users

Administrators can make API requests on behalf of another user by adding the X-Redmine-Switch-User header with the target user’s login name:

curl -H "X-Redmine-API-Key: ADMIN_API_KEY" \
  -H "X-Redmine-Switch-User: john.doe" \
  https://redmine.example.com/issues.json

The response will reflect what the impersonated user can see. Redmine returns 412 Precondition Failed if the specified login does not exist or is not active.

This header is only honored when the requesting user is an administrator.

Choosing an authentication method

Method	Best for
API key (header)	Server-to-server integrations, scripts, CI pipelines.
HTTP Basic Auth	Quick local testing (not available for users with 2FA).
OAuth2	Third-party applications acting on behalf of users.
X-Redmine-Switch-User	Admin automation acting on behalf of specific users.