OAuth 2.0 Authentication

Return to the API v2 Documentation.

OAuth 2.0 Authentication

DMPRoadmap uses OAuth 2.0 for authentication and currently supports the authorization_code grant type.

In the OAuth workflow, an application exchanges an authorization code for an access token, which is then used to authenticate requests to the API.

OAuth Endpoints

Authorization endpoint:

https://example.com/oauth/authorize

Token endpoint:

https://example.com/oauth/token

Endpoint	Description
/oauth/authorize	Used to obtain an authorization code from the user
/oauth/token	Used to exchange an authorization code for an access token

Authorization Code Grant Flow

+-------------+                                +---------------+
| Application |                                | DMPRoadmap |
+-------------+                                +---------------+
       |                                                |
       | 1. Redirect user to /oauth/authorize           |
       |----------------------------------------------->|
       |                                                |
       | 2. User signs in and approves access           |
       |<---------------------------------------------->|
       |                                                |
       | 3. Redirect back with ?code=AUTH_CODE          |
       |<-----------------------------------------------|
       |                                                |
       | 4. POST /oauth/token with code                 |
       |----------------------------------------------->|
       |                                                |
       | 5. Receive access token                        |
       |<-----------------------------------------------|
       |                                                |
       | 6. Call /api/v2/... with Bearer token          |
       |----------------------------------------------->|

To obtain an access token for a specific user, the user must first authorize the request. This is done using the OAuth 2.0 Authorization Code Grant flow.

Step 1 — Request User Authorization

Redirect the user to the authorization endpoint with the required parameters.

Example authorization URL:

https://example.com/oauth/authorize?client_id=12345&redirect_uri=http://127.0.0.1:3000/oauth/callback&response_type=code&scope=read

Parameters used in this request:

Parameter	Description
client_id	The client ID issued when your application was registered
redirect_uri	The URI that the user will be redirected to after authorization
response_type	Must be code for the Authorization Code flow
scope	Specifies the permissions requested

Supported Scopes

Scopes determine which actions the application may perform on behalf of the user.

Scope	Description
read	Allows the application to fetch the user's DMP metadata and download full PDF copies of their DMPs
write	Allows the application to create and update DMPs

Authorization Process

If the authorization request is valid, the following sequence occurs:

1. The user is redirected to the DMPRoadmap sign-in page (if they are not already signed in).

2. After signing in, the user is presented with a page listing the permissions requested by the application (based on the specified scope).

3. The user may approve or deny the request.

4. If the request is approved, the user is redirected to the specified redirect_uri.

The authorization code is included in the query string.

Example:

https://127.0.0.1:3000/oauth/callback?code=MY_AUTHORIZATION_CODE

Authorization codes are short-lived and should be exchanged for an access token as soon as possible.

Step 2 — Exchange the Authorization Code for an Access Token

Once the authorization code is received, it can be exchanged for an access token by sending a request to the token endpoint.

Example request:

curl -X POST https://example.com/oauth/token \
  -H "Accept: application/json" \
  -d "grant_type=authorization_code" \
  -d "client_id=YOUR_CLIENT_ID" \
  -d "client_secret=YOUR_CLIENT_SECRET" \
  -d "code=YOUR_AUTHORIZATION_CODE" \
  -d "redirect_uri=http://127.0.0.1:3000/oauth/callback"

The redirect_uri must match the URI used in the authorization request.

Access Token Response

If the request is successful, the server will return an HTTP 200 OK response along with a JSON payload similar to the following:

{ 
  "access_token":"NEW_ACCESS_TOKEN",
  "token_type":"Bearer",
  "expires_in":7200,
  "refresh_token":"NEW_REFRESH_TOKEN",
  "scope":"read",
  "created_at":1772847413
}

The access_token should be included in the Authorization header when making requests to the API.

Example:

Authorization: Bearer YOUR_ACCESS_TOKEN

Refreshing an Access Token

Access tokens expire after the time specified in expires_in. To obtain a new access token without requiring the user to reauthorize, use the refresh_token returned from the initial token request.

Example Request

curl -X POST https://example.com/oauth/token \
  -H "Accept: application/json" \
  -d "grant_type=refresh_token" \
  -d "client_id=YOUR_CLIENT_ID" \
  -d "client_secret=YOUR_CLIENT_SECRET" \
  -d "refresh_token=YOUR_REFRESH_TOKEN"

Example Response

{
  "access_token": "NEW_ACCESS_TOKEN",
  "token_type": "Bearer",
  "expires_in": 7200,
  "refresh_token": "NEW_REFRESH_TOKEN",
  "scope": "read",
  "created_at": 1772847413
}

Notes

• The refresh_token is obtained from the initial token response.
• A successful request returns a new access_token.
• A new refresh_token is also be returned. Clients should replace the stored refresh token with the new value.
• This request does not require an authorization code or redirect_uri.