First steps

This document provides a step-by-step guide on how to start using A2A APIs quickly and efficiently.
Follow the steps below to integrate your application with A2A and begin leveraging the offered features.

Requirements

• A2A administrator permission.
• Application created in A2A. Access the document on How to create an application for more information.
• Authorization for the application created in A2A. Access the document on How to create an authorization for an application for more information.

Authenticate the application

To access A2A APIs, it's essential to follow the OAuth 2.0 authentication method recommended by senhasegura.
Use the Client ID and Client Secret generated by A2A to obtain an Access Token used to validate and authorize all subsequent API calls.

1. In the HTTP or REST client of your choice, such as Postman, create a collection.
2. In the Authorization > Type tab, select OAuth 2.0.
3. In Configure New Token > Configuration Options > Grant Type, select Client Credentials.
4. In Access Token URL, make a request to the authorization server endpoint. For example, GET {{senhasegura}}/api/oauth2/token
5. In Client ID, enter the value generated when creating the application authorization in A2A.
6. In Client Secret, enter the value generated when creating the application authorization in A2A.
   1. If you are using a tenant and making the request via an IP address, you'll need to pass the tenant parameter along with the request. In the tenant parameter, enter the string containing the tenant's name that will be used for authentication.
7. Click Get New Access Token at the bottom of the page.
8. Click Proceed to open the MANAGE ACCESS TOKENS page and view the generated Access Token.
9. Use this Access Token to make requests to the PAM Core APIs.

Access the document on How to authenticate an application for more information.

In multi-tenant scenarios

• In multi-tenant environments, use the tenant parameter to specify the desired tenant during authentication.
• The value of this parameter must be a string identical to the tenant's subdomain in the URL of the senhasegura instance. For example, for the tenant test accessed via test.senhasegura.com, the value of the tenant parameter would be test.
• Remember: authentication is always restricted to the tenant of the current request. It isn’t possible to generate authorizations for different tenants.
• It’s mandatory to use the tenant parameter when making calls via senhasegura's IP address. In this scenario, automatic tenant identification is unfeasible, making the parameter essential for successful authentication.

Example:

{
  "grant_type":  "client_credentials",
  "client_secret": "your_client_secret",
  "client_id": "your_client_id",
  "tenant": "test"
}

Requests and responses

Requests are made using HTTP methods such as GET, POST, PUT and DEL.

Parameters include id, identifier, hostname, username, among others, and depending on the API call, can be sent in the path of the URL or in the request body.

Responses are returned in JSON format, making it easy to analyze and manage data provided by the API.

Example:
When making a request to the endpoint GET /api/pam/device/14, the API returns the data of the device whose id is 14.

{
    "code": 200,
    "response": {
        "status": 200,
        "message": "Device 14",
        "error": false,
        "error_code": 0,
        "detail": "",
        "mensagem": "Device 14",
        "erro": false,
        "cod_erro": 0
    },
    "tenant": "test",
    "device": {
        "id": "14",
        "hostname": "API device",
        "ip": "10.66.33.17",
        "model": "Gmail",
        "type": "Desktop",
        "vendor": "Linux",
        "site": "AWS",
        "device_domain": "my_device_domain",
        "connectivities": "HTTP:80,SSH:22,MySQL:65535",
        "session_remote_config": "HTTP::",
        "device_tags": "test"
    }
}

Each document contains the description of the response body fields.
Access the document GET | List a device by [id] to see the description of the fields listed in the response above.

Errors

The API returns standard HTTP status codes and includes error messages in the response body to facilitate understanding and troubleshooting.

Example:
The following message returns an error for the case of a device not found.

{
    "code": 400,
    "response": {
        "status": 400,
        "message": "1011: Device not found",
        "error": true,
        "error_code": 1,
        "detail": "",
        "mensagem": "1011: Device not found",
        "erro": true,
        "cod_erro": 1
    },
    "exception": {
        "code": 1011,
        "message": "1011: Device not found",
        "detail": null
    }
}

Refer to the documentation for each method for detailed error descriptions, their possible causes and solutions.

Links to A2A API documentation

Access the following documents for more detailed information and examples:

• PAM Core.
• Informação protegida.
• Usuários relacionados.
• Certificate Manager.
• Dashboards.