Preparing to Make an Authenticated API Request
Last updated
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 from the OAuth2 authentication platform.
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.
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:
The base text for the signature is formed in the following way:
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 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.
The required 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 list or a list separated by the plus sign (+) of the permissions that the application is requesting. If all permissions of the account are required, use the asterisk sign (*) for that purpose.
aud
Address of the authentication platform that issues access tokens. This value must always and exactly be https://identityhomolog.acesso.io
Common cases that DO NOT work:
Inserting 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 time of 1 hour after the moment of issuing the JWT. This value must be numeric. Common cases that DO 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.
iat
The moment of issuing the JWT, specified in seconds since 00:00:00 UTC, January 1, 1970. This value must be numeric.
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 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:
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 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:
Below 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 must be URL encoded. The URL is as follows:
The parameters below are mandatory in the 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 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:
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.
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:
Where token.exp is the timestamp of the token's expiration.
By default, the token sent to the company is valid for 1 hour, but this can be changed. It is recommended to always use the expires_in as a reference and subtract 600 seconds from it to request a new token.
Examples:
Um novo token de acesso pode ser solicitado quando faltar 10 minutos pra expirar.
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 will result in service usage failures.
¹ 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.
