Preparing to make an authenticated request to the API
In this section, you will find how to perform the authentication process for the Unico IDPay product.
Last updated
In this section, you will find how to perform the authentication process for the Unico IDPay product.
Last updated
Copyright © 2024 unico. All rights reserved.
After creating and configuring a service account, your application needs to complete the following steps:
Create a JSON Web Token (JWT), which includes the header, payload, and signature;
Request an access token (AccessToken) from the OAuth2 authentication platform;
Handle the JSON response that the authentication platform will return.
If the response includes an access token, you can use it to make requests to Unico's product APIs for which the service account has access permissions. (If the response does not include an access token, your JWT and token request may be incorrect, or the service account may not have the necessary permissions to access the requested resources.)
The access token generated in the request mentioned above has a default validity of 3600 seconds, but this may vary depending on the security configuration set for your company. When the access token expires, your application should generate a new JWT, sign it, and request a new access token from the authentication platform.
A JWT consists of three parts: a header, a payload, and a signature. The header and payload are JSON objects. These JSON objects are serialized in UTF-8 and then encoded using Base64url encoding¹. This encoding provides resilience against encoding changes in cases of repeated encoding operations. The header, payload, and signature are concatenated with a period (.) character.
A JWT is composed as follows:
The base text for the signature is composed as follows:
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:
The Base64url representation is as follows:
The JWT payload contains information about the JWT, including the requested permissions (scopes), the account requesting access, the issuer, the time when the token was issued, and the token's lifetime. Most fields are mandatory. Just like the JWT header, the payload is a JSON object and is used in the composition of the signature.
The mandatory fields in the JWT are shown in the table below. They can appear in any order within the payload.
iss
The identifier of the service account within the company.
scope
A space-delimited or plus sign (+) list of the permissions the application is requesting. If all permissions of the account are required, use the asterisk (*) symbol for this.
aud
The address of the authentication platform that issues access tokens. This value should always be exactly https://identityhomolog.acesso.io
Common issues that do not work:
Adding a trailing slash at the end of the address:https://identityhomolog.acesso.io/
Using the HTTP protocol instead of HTTPS:http://identityhomolog.acesso.io
exp
The expiration time of the token, specified in seconds since 00:00:00 UTC, January 1, 1970. This value has a maximum duration of 1 hour after the JWT issuance time. It must be numeric. Common issues that do not work:
Using quotes to delimit the value. For example: “1524161193” is a string and will not work. Whereas 1524161193 is a number and will work.
iat
The time of JWT issuance, specified in seconds since 00:00:00 UTC, January 1, 1970. This value must be numeric. Common issue that does not work:
Using quotes to delimit the value. For example: “1524161193” is a string and will not work. However, 1524161193 is a number and will work.
Understand how the conversion works for the issuance (iat) and expiration (exp) fields of the JWT, and also see examples of how to use these field values here. In addition, the 'iat' field must represent the current time in the required format, and the 'exp' field must respect the following calculation:
The representation of the mandatory JSON fields in the JWT payload is as follows:
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:
The same algorithm specified in the JWT header must be used for calculating the signature. 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 the 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 then needs to be encoded in Base64url. The header, payload, and signature should be concatenated with a period character. The result is the JWT. It should be as follows:
Here is an example of a JWT token before Base64url encoding:
Below is an example of the JWT that has been signed and is ready for transmission:
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.
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 should be URL encoded. The URL is shown below:
The following parameters are mandatory in the POST HTTPS request:
grant_type
Use the following text, URL-encoded if necessary: urn:ietf:params:oauth:grant-type:jwt-bearer
assertion
The JWT, including the signature.
If the JWT and the access token request are properly formed, and the service account has the necessary permissions, the authentication platform will return a JSON object containing an access token. Here’s an example of the response from the platform:
The access token returned in the "access_token" field of the JSON object is also a JWT token that should be used in the APIs of Unico's Products. If an error occurs in the request, you can check the error type in the error table by clicking here.
The duration of the access token is variable. Its duration is specified in the "expires_in" field, which is returned along with the access token. The same access token should be used throughout its validity for all API calls to the products.
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 following calculation:
Where token.exp is the timestamp of the token's expiration.
By default, the token sent to the company lasts 1 hour, but it can be changed. The recommendation is to always use the expires_in as the base and subtract 600s from it to request a new token.
Examples:
A new access token can be requested when there are 10 minutes left until expiration.
Do not use a fixed time to obtain a new token, as the duration of the received token may be shorter than the established time, which could cause failures when using the services.
¹ According to RFC 4648 for BaseN encoding, the Base64url format is similar to Base64, except that the '=' character is omitted, and the characters '+' and '/' are replaced by '-' and '_', respectively.
² JSON Web Signature: https://tools.ietf.org/html/rfc7515.
Didn't find something or still need help? If you're already a client or partner, you can reach out through our Help Center.
