# Introduction Digital Commons Data API lets you find and manage research data, you can find out more about Digital Commons Data on [our FAQs page](https://data.mendeley.com/faq) # Authentication Our APIs use OpenID Connect (OIDC) which extends the [OAuth 2.0](https://datatracker.ietf.org/doc/html/rfc6749) authorization protocol for use as an additional authentication protocol, refer to the [OpenID Connect specifications](https://openid.net/specs/openid-connect-core-1_0.html) for more details. Using the standard OIDC/OAuth 2.0 `authorization_code` flow, your client application can authenticate a user the result provided three tokens, which can be used to make API calls on behalf of the user: - `Access token`: A token that can be sent in API requests (as part of the `Authorization` header), this token has a short expiry. - `Refresh token`: A token that can be used to create a new access token without requiring the user to login again. - `Identity token`: A token containing claims (information) about the logged in user like name, email and roles. Digital Commons Data partially supports `client_credentials` flow, however since the result of this flow does not contain a authenticated user (resource owner) some endpoints do not support access tokens from this flow. It is highly recommended to use a [OAuth2 or OIDC client library](https://oauth.net/code/) to implement the authorization flows and obtain tokens. ## Register a Client To use our APIs you will need to register a client, currently you will need to [get in touch](mailto:data-queries@mendeley.com?subject=Digital%20Commons%20Data%20API%20client%20request) providing: - A contact email address - Company or personal name - Brief description of the use case for using the API ## Obtain a Token Using Authorization Code flow Steps: 1. Authorize user 2. Exchange authorization code for tokens 3. Use access token in an API request ### Authorize user ``` GET https://auth.data.mendeley.com/oauth2/authorize?response_type=code&client_id=&redirect_uri=&scope=openid%20profile%20email%20dcd:profile&state= ``` The above URL will redirect the user to sign in to the Digital Commons Data application. Once signed in, the response triggers an HTTP 302 status, redirecting back to with a code query parameter. This is the authorization code required for the next stage. ### Exchange authorization code for tokens ``` curl -X POST \ -H "Content-Type: application/x-www-form-urlencoded" \ -u ":" \ -d "grant_type=authorization_code&code=&redirect_uri= https://auth.data.mendeley.com/oauth2/token ``` Example response: ``` { "access_token":"aaa.bbb.ccc", "refresh_token":"def", "scope":"openid profile email dcd:profile", "id_token":"iii.ttt", "token_type":"Bearer", "expires_in":299 } ``` ### Use access token in an API request Using the `access_token` value from the previous response, set the `Authorization` Bearer token, for example: ``` curl -X GET \ -H "Content-Type: application/json" \ -H "Authorization: Bearer aaa.bbb.ccc" \ https://api.data.mendeley.com/datasets ``` ## Obtain a Token Using Client Credentials flow Steps: 1. Create an access token 3. Use access token in an API request ### Create an access token ``` curl -X POST \ -H "Content-Type: application/x-www-form-urlencoded" \ -u ":" \ -d "grant_type=client_credentials&scope= https://auth.data.mendeley.com/oauth2/token ``` Example response: ``` { "access_token":"aaa.bbb.ccc", "token_type":"Bearer", "expires_in":299 } ``` ### Use access token in an API request Using the `access_token` value from the previous response, set the `Authorization` Bearer token, for example: ``` curl -X GET \ -H "Content-Type: application/json" \ -H "Authorization: Bearer aaa.bbb.ccc" \ https://api.data.mendeley.com/datasets ``` ## OAuth2 Server Details