API Authentication

Return to the API Overview

The DMPTool uses Oauth2 for authentication and supports both the client_credentials and authorization_code grant types. In OAuth workflows, you pass your API credentials to the DMPTool to acquire an access token. The access token is then used to interact with the API.

Standard Access

To acquire an access token for standard access you must send a request as follows:

screenshot of OAuth client credentials workflow

To retrieve an access token in the standard scenario you must specify grant_type=client_credentials and provide your client_id and client_secret. For example:

curl -v https://dmptool.org/oauth/token \
  -X POST \
  -H "Accept: application/json"
  -d "grant_type=client_credentials&client_id=12345&client_secret=ABCDEFG"

You can also submit specific scopes in the request for a token. For example -d "grant_type=client_credentials&scope=read_dmps&client_id=12345&client_secret=ABCDEFG"

By default it assumes you are requesting both public.

The following scopes are available at this time:

public (allows you to fetch the list of templates and the list of DMPs ... abridged metadata)
read_dmps (allows you to fetch individual DMPs ... full metadata or their PDF)
create_dmps (allows you to create DMPs)

Protected Access

To acquire an access token for a specific user (protected access) the user must first authorize the request. Once the user has authorized the request, you can then retrieve an access token that will allow you to access their data:

screenshot of OAuth user authorization workflow

To retrieve an authorization code in the protected scenario you must specify grant_type=authorization_code and provide your client_id, redirect_uri and scope(s) you want access to. For example:

curl -v https://dmptool.org/oauth/authorize?\
  client_id=12345\
  &redirect_uri=http%3A%2F%2Flocalhost%3A3001%2Foauth2%2Fcallback\
  &response_type=code\
  &scope=read_dmps

Note that the redirect_uri MUST match one of the redirect URIs you have defined on the 'Developer Tools' section of your DMPTool user profile. This value should also be properly escaped (see above).

Scopes are used to identify what data and functions you will be able to perform on behalf of the user. The system currently supports the following scopes:

read_dmps - This scope allows you to fetch the user's DMP metadata as well as full PDF copies of their DMPs
create_dmps - This scope allows you to create a DMP on the user's behalf
edit_dmps - This scope allows you to add related identifiers to a DMP on the user's behalf

Assuming the request was valid, the following sequence of events occurs:

the user will be sent to the sign in page (if they are already signed in on a different browser tab/window then this step is skipped).
the user will be presented with a page detailing the list of data you have requested access to (based on the scope(s) you specified in the request (e.g. "read and download your DMPs"). The page allows the user to either approve or deny the request.
after the user has made their decision a call is made to the redirect_uri you specified in the request. If the user approved your access, then an authorization code is returned. For example https://localhost:3001/oauth2/callback?code=MY_AUTHORIZATION_CODE

If your redirect_uri received an access token, you can then use it to fetch an access token for the user. For example:

curl -v https://dmptool.org/oauth/token \
  -X POST \
  -H "Accept: application/json"
  -d "grant_type=authorization_code&client_id=12345&client_secret=ABCDEFG&code=MY_AUTHORIZATION_CODE&redirect_uri=http%3A%2F%2Flocalhost%3A3001%2Foauth2%2Fcallback"

Note that you must pass the redirect_uri again in this 2nd call and it must match the one used when retrieving the authorization code.

The access tokens received in this scenario are long lived and can be stored within your system if you intend to interact with the DMPTool API for an extended period of time. This prevents the user from having to sign in/authorize access every time you need to make an API request.

Note: For those using protected access The DMP JSON metadata will include a dmproadmap_privacy flag that informs you of the authorized user's specified visibility setting for the DMP. While the user gave you permission to access their DMPs, we ask you to please adhere to their specified visibility policy when it comes to handling the DMP meatdata and/or PDF copy within your system. The possible visibilities are: private, organizational, public. Please note that 'private' means they do not want to share the DMP and organizational means that they are willing to share the DMP with other members of their organization or research project team.

Access Token Responses

If the token request was successful an HTTP 200 OK will be issued along with the following JSON response:

{
  "access_token": "cdmn2PW9W8w_yiaIprohLN7iDTTfVPNKNnLK1LT4how",
  "token_type": "Bearer",
  "scope": "public read_dmps",
  "created_at": 1618500601
}

Note that in the case of a token received via the protected access workflow ( when using grant_type=authorization_code) the authorized scope(s) are returned as part of the response. If you later need access to other scopes, you will need to acquire the user's authorization again.

Authorization Code Responses

As noted above, the authorization code for a user is sent to you via your redirect URI. It is passed along in the query string as code=12345. The codes are short lived and should be used to fetch a long-lived access token as soon as possible.

Authorization Code and Access Token Errors

If your client_id and client_secret or client_id and code are invalid you would receive an HTTP 401 Unauthorized response with the following JSON:

{
  "error": "invalid_client",
  "error_description": "Client authentication failed due to unknown client, no client authentication included, or unsupported authentication method."
}

For any other errors you will receive an HTTP 400 Bad Request with JSON containing more information about the error:

{
  "error": "invalid_request", 
  "error_description": "Missing required parameter: grant_type."
}

API Response when an access token is no longer valid

In subsequent calls to the API, if the token becomes invalid for any reason, you would receive an HTTP 401 Unauthorized along with the following JSON response which provides more details on what went wrong:

{
  "api_version": 2,
  "source": "GET /api/v2/templates",
  "time": "2021-05-18T09:34:47-07:00",
  "code": 401,
  "message": "Unauthorized",
  "total_items": 0,
  "items": [],
  "errors": [
    "token is invalid, expired or has been revoked"
  ]
}