Authentication

Create Token
Refresh Token

This endpoint allows authenticating a user to obtain a token. Tokens can later be used to access the rest of methods of the BigContent API. Tokens are based on the oauth2 standard, but are exposed through custom operations.

Create Token

POST https://api.everisbigcontent.com/edms/rest/v1/auth/token

Creates a user token. The token is valid for 1 hour, after that we need to get a new one, either by Create Token or Refresh Token.

In case of success, the response body contains the token as well as other information in a JSON object.

Parameters

HTTP Headers

HTTP headers allow pass additional information with the request or the response. BigContent headers are used for recurrent details like authentication or document store.

Table 1. Headers
Name	Example	Description
`Content-Type`	`application/json`	The Content-Type entity header is used to indicate the media type of the resource. In this case, it must be `application/json`

Body

As indicated by headers, the body of the http request must be a JSON (Content-Type: application/json).

{
  "clientId": "CLIENT_ID",
  "user": "USER",
  "secret": "PASSWORD"
}

Table 2. Body
Name	Value	Detail
clientId	`8gt5e9a4-7d4e-7aq9-1csw-14aq7r8t9y5a`	Client id provided during the registration
user	`john@company.com`	Fully qualified name of the user account
secret	`4FG56w4dgeA`	User account secret

Responses

Success

Successful responses can be easily identified being always 20x (e.g. 200, 201).

Table 3. Success response
Field	Example	Description
Status code	`200`	`OK`
`Content-Type`	`application/json`	The Content-Type entity header is used to indicate the media type of the resource. In this case, it must be `application/json`
Body	JSON response	JSON object containing the access and refresh token

JSON response

{
  "accessToken" : "ha9r6DG4e5AQ84gferAd8EQ...",
  "refreshToken" : "FEEA84g7gfhjt52wd5AFE4...",
  "expirationDate" : "2018-10-24T07:10:51.709Z",
  "expireAfter" : 3600
}

Table 4. Token
Name	Value	Detail
accessToken	`ha9r6DG4e5AQ84gferAd8EQ…`	Authentication token required for BigContent operations (to be used in `Authorization` header)
refreshToken	`FEEA84g7gfhjt52wd5AFE4…`	Additional token required to obtain a new token from a previous authentication request [refresh]
expirationDate	`2018-10-24T07:10:51.709Z`	Is the date when the token expires
expireAfter	`3600`	Time to live of the token

Error

In case of error, the response body contains a JSON object with additional information:

span-id: auto-generated identifier of the request. Please provide this when asking for support in our forum.
message: descriptive message of the error. This is aimed for developers and is specially important for Bad Request errors., where contains hints on how to fix the request.

Error messages should not be used to validate errors since they may be subject to change.

Example

{
  "span-id" : "7eb38962-2618-85f9-brte-4f15f6729590",
  "message" : "No match found for the Id"
}

Table 5. Error messages
Status code	Message	Description
400	`Malformed JSON exception (line _, col _): …`	The JSON body has a bad structure. Message points where is the problem with line and column numbers as well as what is the problem (e.g. double "{", or a missing ",", …)
400	`_ is null or empty`	Field (e.g. clientId, user or secret) was sent as null/empty value
400	`A not empty _ is expected`	Field (clientId, user, or secret) is missing from the JSON
401	`Bad credentials`	User, password or clientId value(s) are not correct
415	`Content type _ not supported`	The Content-Type header is not correctly set
500	`Internal server error`	If it happens consistently, please report it on our forum

Code examples

cURL
Java
Node.js

curl "https://api.everisbigcontent.com/edms/rest/v1/auth/token" \
-X POST \
-H 'Content-Type: application/json' \
-d "{ \"clientId\": \"$client_id\", \"user\": \"$user\", \"secret\": \"$password\" }"

import org.apache.http.client.methods.CloseableHttpResponse;
import org.apache.http.client.methods.HttpPost;
import org.apache.http.entity.StringEntity;
import org.apache.http.impl.client.CloseableHttpClient;
import org.apache.http.impl.client.HttpClients;
import org.apache.http.util.EntityUtils;

String url = "https://api.everisbigcontent.com/edms/rest/v1/auth/token";
String JSON = "{ \"clientId\": \"8gt5e9a4-7d4e-7aq9-1csw-14aq7r8t9y5a\", \"user\": \"john@company.com\", \"secret\": \"4FG56w4dgeA\"}";

CloseableHttpClient client = HttpClients.createDefault();
HttpPost httpPost = new HttpPost(url);
httpPost.setHeader("Content-type", "application/json");
httpPost.setEntity(new StringEntity(JSON));
CloseableHttpResponse response = client.execute(httpPost);
String token = EntityUtils.toString(response.getEntity(), StandardCharsets.UTF_8);

var request = require('request');

var token
request.post({
  headers: [{
    'Content-Type': 'application/json'
   }],
   url: 'https://api.everisbigcontent.com/edms/rest/v1/auth/token',
   json: {
    "clientId": "8gt5e9a4-7d4e-7aq9-1csw-14aq7r8t9y5a",
    "user": "john@company.com",
    "secret": "4FG56w4dgeA"
  }
}, function (error, response, body) {
  token = body;
});

Refresh Token

POST https://api.everisbigcontent.com/edms/rest/v1/auth/refresh

Creates a new user token without the need of the user credentials. The token is valid for 1 hour, after that we need to get a new one, either by Create Token or Refresh Token.