To use server-to-server interactions, you need to request the creation of a service account through the project manager responsible for your company by providing the following information: company name, application name, name, email, and phone number of the person responsible for the application within the company. Separate accounts are required for the Homologation and Production environments.

Once this information is received, a service account responsible for authenticating your application will be created, and an email will be sent to generate the key pair for the account. A service account credential includes a unique account name, a company identifier (Tenant ID), and at least one key pair (public and private). After generating the keys, you will only receive the private key (a .key.pem file) along with the payload that must be used to construct the JWT. This payload will follow the format below:

If you need the public key for system configuration, please contact the project manager responsible for your account. Alternatively, you can generate a public key using the following OpenSSL command:

openssl req -x509 -new -nodes -sha256 -days 720 \
-key fileName.key.pem -out fileName.cert.pem

Still need help?​

Didn't find something or still need help? If you're already a client or partner, you can reach out through our Help Center.

After creating and configuring a service account, your application needs to complete the following steps:

1. Create a JSON Web Token (JWT), which includes the header, payload, and signature.

2. Request an Access Token from the OAuth2 authentication platform.

3. Process the JSON response returned by the authentication platform.

If the response includes an access token, you can use it to make requests to Unico product APIs for which the service account has access permissions. (If the response does not include an access token, your JWT or token request may be incorrect, or the service account might lack the necessary permissions to access the requested resources.)

The access token generated in the above request has a default validity of 3600 seconds, but this may vary based on the security configuration set for your company. When the access token expires, your application must generate a new JWT, sign it, and request a new access token from the authentication platform.

1 - Creating the JWT

A JWT (JSON Web Token) consists of three parts: a header, a payload, and a signature. The header and payload are JSON objects, which are serialized in UTF-8 and then encoded using Base64url encoding. This encoding ensures resilience against modifications due to repeated encoding operations. The header, payload, and signature are concatenated using a period (.) separator.

A JWT is structured as follows:

{Header in Base64url}.{Payload in Base64url}.{Signature in Base64url}

The base text for the signature is formed in the following way:

{Header in Base64url}.{Payload em Base64url}

1.1 - Forming the JWT Header

The header consists of two fields that specify the signing algorithm and the token format. Both fields are mandatory, and each field has only one value. Service accounts rely on the RSA SHA-256 algorithm and the JWT token format.

As a result, the JSON representation of the header is as follows:

{"alg":"RS256","typ":"JWT"}

The Base64url representation is as follows:

eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9

This ensures that both header and payload are properly encoded before signing, which is crucial for secure authentication.

1.2 - Forming the JWT Payload

The JWT payload contains information about the JWT, including the requested permissions (scopes), the account requesting access, the issuer, the time the token was issued, and the token's lifespan. Most fields are mandatory. Like the JWT header, the payload is a JSON object and is used in the composition of the signature.

1.3 - Required Fields

The required fields in the JWT are shown in the table below. They can appear in any order within the payload.

Understand how the conversion works for the issuance (iat) and expiration (exp) fields of the JWT, and also see examples of how to use the values of these fields here. Additionally, the "iat" field should reflect the current time in the required format, and the "exp" field must adhere to the calculation below:

exp = iat + 3600

The representation of the mandatory JSON fields in the JWT payload is as follows:

{
  "iss": "service_account_name@tenant_id.iam.acesso.io",
  "aud": "https://identityhomolog.acesso.io",
  "scope": "*",
  "exp": 1626296976, //This is just an example. Use the current value generated here.
  "iat": 1626293376 //This is just an example. Use the current value generated here.
}

1.4 - Calculating the Signature

The JSON Web Signature (JWS) specification is the mechanism that guides the calculation of the signature for a JWT. The input content for the signature calculation is the byte array of the following content:

{Header in Base64url}.{Payload in Base64url}

The same algorithm specified in the header of the JWT must be used for the signature calculation. The only signature algorithm supported by the OAuth2 authentication platform is RSA using SHA-256. It is expressed as RS256 in the alg field of the JWT header.

Sign the UTF-8 representation of the input content using SHA256withRSA (also known as RSASSA-PKCS1-V1_5-SIGN with SHA-256 hash) with the private key that was created and associated with the service account (the .key.pem file generated from the request received by email). The output content will be a byte array.

The signature must then be encoded in Base64url. The header, payload, and signature must be concatenated with a period (.). The result is the JWT. It should be in the following format: {Header in Base64url}.{Payload in Base64url}.{Signature in Base64url} Below is an example of a JWT token before Base64url encoding:

{Header in Base64url}.{Payload in Base64url}.{Signature in Base64url}

Below is an example of a JWT token before Base64url encoding:

{"alg":"RS256","typ":"JWT"}.
{
  "iss": "service_account_name@tenant_id.iam.acesso.io",
  "aud": "https://identityhomolog.acesso.io",
  "scope": "*",
  "exp": 1626296976, //This is just an example. Use the current value generated here.
  "iat": 1626293376 //This is just an example. Use the current value generated here.
}.
[byte array from signature]

Below is an example of the JWT that has been signed and is ready for transmission:

eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJzZXJ2aWNlX2FjY291bnRf
bmFtZUB0ZW5hbnRfaWQuaWFtLmFjZXNzby5pbyIsImF1ZCI6Imh0dHBzOi8vaWRlbnRpdHlob21vbG9nLmFjZXNzby5pbyIsInNjb
3BlIjoiKiIsImV4cCI6MTYyNjI5Njk3NiwiaWF0IjoxNjI2MjkzMzc2fQ.JsymP3NZdgCSqeNlgsOM2
-AQ7M450NxFnZnnaKSu4Q8g12QGEIvvM4EhCokUHfwk5s7pOpm2UD_Ng3Hb5g_wgrjfiVSLWH5Q2wYg1AvfLqo
YSoJWaMHm9KL0kpv32XdDD8TZVR-MVd2VBHmCMVbV6gvk8buUoK1HZDN7g84PaY3bfgcB3RKU-
H55lR8yyJjZxToIv17-wfla2G99uaMEFNGX0ZSE7ETn5Z8-WypmFrNAK0TM58upzvfVI6_-
gY4cj4iQvmRbuvxsAaGiHA2xd0RVm2Mrx-gQtdPqtbZPuQcH7k64Z_EOQBgiGTgVjucyHD6zBijr_P-
2mhIxuecNSw

It is also possible to use pre-established libraries to create the JWT. As a reference, you can find a list of libraries on the jwt.io website.

2 - Making a Request for an Access Token

After generating the signed JWT, an application can use it to request an access token. The access token request is a POST HTTPS request, and the body must be URL encoded. The URL is as follows:

https://identityhomolog.acesso.io/oauth2/token

The parameters below are mandatory in the request:

POST /oauth2/token HTTP/1.1
Host: identityhomolog.acesso.io
Content-Type: application/x-www-form-urlencoded

grant_type=urn%3Aietf%3Aparams%3Aoauth%3Agrant-type%3Ajwt-
bearer&assertion=eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJzZXJ2aWNlX2FjY
291bnRfbmFtZUB0ZW5hbnRfaWQuaWFtLmFjZXNzby5pbyIsInN1YiI6InVzZXJfaWRlbnRpZmllciIs
ImF1ZCI6Imh0dHBzOi8vaWRlbnRpdHlob21vbG9nLmFjZXNzby5pbyIsInNjb3BlIjoiKiIsImV4cCI
6MTMyODU1NDM4NSwiaWF0IjoxMzI4NTUwNzg1fQ.TjH-mTtwP6tBB93O1sDPaAA6yUF7N2-HZDlpIPz
bf_dxO8A6KZuRWG8ZnICrxX56qj0HREiMlYy27XJgxowrUa0JHvbqc8HJkT7-6Mh7J67UnubZKG1-hi
6jDtkC9BIXBcOhtkNUfZvZetXjLzsRsSDkqxdMtzYZwkRlocvaxL5QXiQhweeEwK_Ux81Adh3z0EIhT
yl7CKJLJ69PuHS7s9IdrjUl79owipp4LF1FvtMhoe7YIL69ohPgFqSv_-Y9qpPdW6be3OEAyKlOM08S
ZBbHBwW4XMvw3uZjTY1sgJ4cBoxrftDpjYOw34oPOKxirqc5-90uOCYe1O1hRtG45w

3 - Handling the response from the authentication platform​

If the JWT and the access token request were properly formed and the service account has the necessary permissions, then the response from the authentication platform returns a JSON object containing an access token. Here’s an example of a response from the platform:

{
  "access_token": "<access_token>",
  "token_type": "Bearer",
  "expires_in": "3600"
}

The access token returned in the “access_token” field of the JSON object is also a JWT that should be used for the APIs of Unico’s products. If an error occurs in the request, you can check the type of error in the error table by clicking here.

4 - The duration of the access token

The duration of the access token is variable. Its duration is specified in the "expires_in" field, returned along with the access token. The same access token should be used during its validity for all calls to the product APIs.

Do not request a new access token until the validity of the current token is nearing its end. We recommend a margin of 600 seconds (10 minutes). To do this, perform the calculation:

decoded token:
new Date(token.exp - 600)

Where token.exp is the timestamp of the token's expiration.

Examples:

Standard scenario:
expires_in: 3600 (1h) - Token generation at 2:42 PM

Request a new token only at 3:32, that is, 2:42 + (3600 - 600)

Scenario with altered duration:
expires_in: 7200 (2h) - Token generation at 2:42 PM

Request a new token only at 4:32, that is, 2:42 + (7200 - 600)

A new access token can be requested when there are 10 minutes left until expiration.

• ¹ According to RFC 4648 for BaseN encoding, the Base64url format is similar to the Base64 format, except that the character = should be omitted, and the characters + and / should be replaced with - and _, respectively.

• ² JSON Web Signature: https://tools.ietf.org/html/rfc7515.

Still need help?​

Didn't find something or still need help? If you're already a client or partner, you can reach out through our Help Center.

The errors returned in the request can be identified by the codes below and have the following structure:

Download the file below, import it into Postman, and replace the values of the parameters "service_account," "tenant_id," and "secret_key" to test the request.

To use the IDCloud platform, you must authenticate via access token using the OAuth2 authentication system. Unico’s OAuth2 authentication supports server-to-server interaction between a web application and Unico's services.

In this setup, you will need a service account, an impersonal account that belongs to your application rather than to an individual user. Your application calls Unico’s APIs on behalf of the service account, so no users are directly involved. This setup is called “two-legged OAuth,” or “2LO.” Typically, an application uses a service account when it calls Unico’s APIs to work with its own data rather than user data.

Still need help?

Didn't find something or still need help? If you're already a client or partner, you can reach out through our .