📘

What will you learn from this article?

• Types of authentication
• Differences between tokens
• Creating your API keys via the dashboard
• How to create tokens via API
• How to use the live_token and the test_token
• Request Signature (RSA)

Types of authentication

Authentication in iugu is performed using an API key, which allows the system to identify your account and grant the necessary permissions to communicate with iugu on behalf of the associated account.

There are three available authentication methods, with the recommended one being the use of HTTP Basic Auth. The second option is authentication via Bearer Authentication. The third alternative is sending the API Token as a parameter named api_token.

live_token, test_token, and user_token

1. live_token: use it for actions in the production environment.

2. test_token: use it for actions in the test environment (staging/sandbox).

3. user_token: use it for requests to the APIs:

   API Token

   API	Endpoint
   Create API Token	v1/{account_id}/api_tokens
   Remove API Token	v1/{account_id}/api_tokens/{id}
   Renew User API Token	v1/profile/renew_access_token
   List Subaccount API Tokens	v1/retrieve_subaccounts_api_token

   Subaccount

   API	Endpoint
   Update Subaccount	v1/accounts/{id}
   Send Subaccount Verification	v1/accounts/{account_id}/request_verification

How to access the user_token?

1. In the 200 OK response from the endpoint Create Subaccount — /v1/marketplace/create_account.
2. Or in the 200 OK response from the endpoint List Subaccount API Tokens — /v1/retrieve_subaccounts_api_token.

🚧

Important

• The endpoints Create Subaccount and List Subaccount API Tokens can only be requested by the Master Account.
• Use the live_api_token.

Create api_token

There are two ways to create an api_token:

1. Via Alia
2. Via API

Alia

1. Access alia.iugu.com > Settings
2. API Integrations > New
3. Choose between Test or Production
4. Add a description, e.g., "My API key"
5. Click Save.

🚧

Important

• This api_token will only be visible for 1 hour. After that, it will be hidden.
• The creation of api_tokens depends on approval from the Account Administrators.

API

Use the endpoint Create API Token — /v1/{account_id}/api_tokens.

Example Request and Response

curl --request POST \
     --url 'https://api.iugu.com/v1/{account_id}/api_tokens?api_token={api_token}' \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data '
{
  "api_type": "TEST",
  "description": "My Test API Key"
}
'

{
  "id": "A0036E328D254004AEA7FD9FE808CDA5",
  "token": "048e378481b750ffbc3ab9e0c0fee11",
  "api_type": "TEST",
  "description": "My Test API Key",
  "created_at": "2024-06-16T13:31:04-03:00"
}

📘

Security Tip 🔐

We recommend updating your API key every 30 days. Keeping the key updated is essential to prevent misuse in case of information leaks.

Remember that your API key acts like a password, authorizing your transactions automatically and securely.

How to use the live_token and test_token

HTTP Basic Auth

To generate the HTTP Basic Auth header for the request, follow these steps:

1. Have the API key, whether for testing or production.

2. Encode the API key, followed by the character “:” at the end of the key, in Base64 format.
   Example: 5AA555555555555555555555555555555CC55555555555555555555555555DD5:
   Base64 encoding of this key: NUFBNTU1NTU1NTU1NTU1NTU1NTU1NTU1NTU1NTU1NTU1Q0M1NTU1NTU1NTU1NTU1NTU1NTU1NTU1NTU1NURENTo=

3. Add the “Authorization” field in the header with the encoded API key value.
   Example: --header 'Authorization: Basic NUFBNTU1NTU1NTU1NTU1NTU1NTU1NTU1NTU1NTU1NTU1Q0M1NTU1NTU1NTU1NTU1NTU1NTU1NTU1NTU1NURENTo='

Request Example

curl --location --request GET 'https://api.iugu.com/v1/customers' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--header 'Authorization: Basic {apitoken in base64}' \
--header 'Cookie: __cfruid=df598e45cd90947e522e12ec895a84f7059cacbc-1627922464' \
--data-raw ''

 

api_token Parameter

Requests allow the inclusion of a parameter called api_token, where you can send the previously generated API Token instead of using HTTP Basic Auth.

Bearer Authentication

It is also possible to use Bearer authentication.

To generate the HTTP Bearer Auth header, follow these steps:

1. Have the API key, whether for testing or production.

2. Encode the API key, followed by the character “:” at the end of the key, in Base64 format.
   Example: 5AA555555555555555555555555555555CC55555555555555555555555555DD5:
   Base64 encoding of this key: NUFBNTU1NTU1NTU1NTU1NTU1NTU1NTU1NTU1NTU1NTU1Q0M1NTU1NTU1NTU1NTU1NTU1NTU1NTU1NTU1NURENTo=

3. Add the “Authorization” field in the header with the encoded API key value.
   Example: --header 'Authorization: Bearer NUFBNTU1NTU1NTU1NTU1NTU1NTU1NTU1NTU1NTU1NTU1Q0M1NTU1NTU1NTU1NTU1NTU1NTU1NTU1NTU1NURENTo='

Request Example

curl --location --request GET 'https://api.iugu.com/v1/customers' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {apitoken in base64}' \
--header 'Cookie: __cfruid=95dfe99ff2d3d94d649675cf8cb7491b4bda25b7-1641564409' \
--data-raw ''

 

Authentication with RSA Signature

What is RSA Signature?

An RSA Signature in APIs is an encryption method that uses the RSA algorithm to ensure the authenticity and integrity of messages exchanged between a client and a server. It involves creating a digital signature using a private key, which can be verified by anyone with the corresponding public key. This ensures that the message was sent from a trusted source and has not been altered during transmission.

Required Endpoints

The endpoints that have Cash Out characteristics require this authentication. They are:

Libraries

As an alternative to the manual flow in this article, use our libraries: RSA Library. The available languages are:

• Ruby
• Java
• Node.js
• PHP
• Python

Would you prefer a video tutorial?

Watch our Webinar hosted by one of our Engineers (on Portuguese-BR):

How about a Recipe?🧪

Here’s a suggestion for how your script (in Ruby) could be developed:

Before You Begin ⚠️

Some important points before starting:

1. This is only possible in production (live_mode).
2. Only one encrypted api_token is allowed per account.
3. Access to Alia is required for the creation of the api_token.
   1. It is not possible to use the endpoint Create API Token — v1/{account_id}/api_tokens as an alternative.
4. This process requires the use of OpenSSL.
5. Create a folder to store the OpenSSL files.
6. Navigate to this folder using the command prompt.

After completing these steps, continue with this guide.

Linux Users

Copy commands will be used in this step-by-step guide. Make sure that xclip or xsel is installed on your system. You can install it with:

$ sudo apt-get install xclip