1.1. Authentication

MetaAccess APIs use the oAuth 2.0 protocol for authentication and authorization. The simplicity of oAuth 2.0 allows developers to start using and developing against MetaAccess APIs almost immediately, the only thing which has to be done, before starting integration, is to register your application and obtain unique set of Client Key and Client Secret from our oAuth Portal.

This step provides you ways to authorize with our platform to archive an access token which is required in each API as a parameter for security and authentication reasons.

We support 2 authorization types below:


1. Authorization Code grant type - User Authorization for server side applications

The authorization code grant type is used to obtain both access tokens and refresh tokens and is optimized for confidential clients. Since this is a redirection-based flow, the client must be capable of interacting with the resource owner's user-agent (typically a web browser) and capable of receiving incoming requests (via redirection) from the authorization server.

Obtain authentication code

To obtain an access token which is required in each API as a parameter for security and authentication reasons with Authorization Code grant type, you have to obtain an authentication code first.

https://gears.opswat.com/o/oauth/authorize?client_id=YOUR_CLIENT_KEY&redirect_uri=YOUR_REDIRECT_URI&response_type=code

Request example

curl https://gears.opswat.com/o/oauth/token \
-d 'client_id=LWDP7P9ZMJ2LBF8AMOMJLFNPMMLO953AVQ4C9YFF52R6TEST' \
-d 'redirect_uri=http://127.0.0.1/opswat' \
-d 'response_type=CODE'

If the user of your application has never authorized access to this resources, they will be prompted by an authorization page and will be asked to authorize access by your Application to their protected resources.

images/download/attachments/41124097/image2018-2-28_11-25-55.png
User has to be logged in through Single Sign On in order to see this page

After accepting the authorization step, the user will be redirected to your callback URL: https://YOUR_REDIRECT_URI/?code=YOUR_AUTHENTICATION_CODE

Example

http://127.0.0.1/opswat?code=Cne7iR

Obtain access token

This step gives you an access token which is required in each API and a refresh token which is used to extend your access token.

https://gears.opswat.com/o/oauth/token?client_id=YOUR_CLIENT_KEY&client_secret=YOUR_CLIENT_SECRET&redirect_uri=YOUR_REDIRECT_URI&grant_type=authorization_code&&code=YOUR_AUTHENTICATION_CODE

Request example

curl https://gears.opswat.com/o/oauth/token \
-d 'client_id=LWDP7P9ZMJ2LBF8AMOMJLFNPMMLO953AVQ4C9YFF52R6TEST' \
-d 'client_secret=7NTAABZ8DBCMCK41SDWAZ5OAERGB846KCVIQ1LHL2G4NTEST' \
-d 'grant_type=authorization_code' \
-d 'redirect_uri=http://127.0.0.1/opswat' \
-d 'code=Cne7iR

Response Example

{
"access_token": "TEST7P9ZMJ2LBF8AMOMJLFNPMMLO953AVQ4C9YFF52R61234",
"token_type": "bearer",
"refresh_token": "TESTABZ8DBCMCK41SDWAZ5OAERGB846KCVIQ1LHL2G4N1234",
"expires_in": 43199,
"scope": "read",
"client_id": "2YotnFZFEjr1zCsicMWpAA"
}

Refresh Access Token

The grant type refresh_token is used to extend client's authorization of a user's resources and to receive additional access_tokens.

https://gears.opswat.com/o/oauth/token?client_id=YOUR_CLIENT_KEY&client_secret=YOUR_CLIENT_SECRET&grant_type=refresh_token&refresh_token=YOUR_REFRESH_TOKEN

Request Example

curl https://gears.opswat.com/o/oauth/token \
-d 'grant_type=refresh_token' \
-d 'client_id=LWDP7P9ZMJ2LBF8AMOMJLFNPMMLO953AVQ4C9YFF52R6TEST' \
-d 'client_secret=7NTAABZ8DBCMCK41SDWAZ5OAERGB846KCVIQ1LHL2G4NTEST' \
-d 'refresh_token=TESTABZ8DBCMCK41SDWAZ5OAERGB846KCVIQ1LHL2G4N1234'

Response Example

{
"access_token": "TEST7P9ZMJ2LBF8AMOMJLFNPMMLO953AVQ4C9YFF52R64567",
"token_type": "bearer",
"refresh_token": "TESTABZ8DBCMCK41SDWAZ5OAERGB846KCVIQ1LHL2G4N4567",
"expires_in": 43199,
"scope": "read",
"client_id": "2YotnFZFEjr1zCsicMWpAA"
}

If you provide an invalid refresh token, the server will return following response:

{
"error": "invalid_grant",
"error_description": "Invalid refresh token: INVALID_TOKEN"
}

2. Client Credentials grant type - No log in required from a user

Client credentials grant type is beneficial for use cases such as service calls or calls on behalf of the user who created the client application and has implicit access to the resources.

images/download/attachments/41124097/infor.png The client credentials grant type must be used by only confidential clients and has to be always used through a secure connection.

https://gears.opswat.com/o/oauth/token?client_id=YOUR_CLIENT_KEY&client_secret=YOUR_CLIENT_SECRET&grant_type=client_credentials

Request Example

curl https://gears.opswat.com/o/oauth/token \
-d 'client_id=LWDP7P9ZMJ2LBF8AMOMJLFNPMMLO953AVQ4C9YFF52R6TEST' \
-d 'client_secret=7NTAABZ8DBCMCK41SDWAZ5OAERGB846KCVIQ1LHL2G4NTEST' \
-d 'grant_type=client_credentials'

Response Example

{
"access_token": "TEST7P9ZMJ2LBF8AMOMJLFNPMMLO953AVQ4C9YFF52R64567",
"token_type": "bearer",
"expires_in": 43199,
"scope": "read",
"client_id": "2YotnFZFEjr1zCsicMWpAA"
}

If you provide invalid client credentials, the server will return the following error:

{
"error": "invalid_client",
"error_description": "Bad client credentials"
}