First steps
  • 3 minutes to read
  • Dark
    Light
  • PDF

First steps

  • Dark
    Light
  • PDF

Article summary

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

Requirements


Authenticate the application

Info

My Safe APIs use OAuth 2.0 as authentication method.

After creating the application and its authorization, use the Client ID and Client Secret generated by MySafe to obtain an Access Token that will be used to validate and authorize all subsequent API calls.

Access the document on How to view an access key authorization for more information.

  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

  1. In Client ID, enter the value generated when creating the application authorization in MySafe.

  2. In Client Secret, enter the value generated when creating the application authorization in MySafe.

    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.
  3. Click Get New Access Token at the bottom of the page.

  4. Click Proceed to open the MANAGE ACCESS TOKENS page and view the generated Access Token.

  5. Use this Access Token to make requests to the MySafe APIs.

Attention

By default, senhasegura creates a 1 hour validity token.

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, and PUT.

Parameters include identifier, name, note, among others, and depending on the API call, can be sent in the path of the URL, in the request body or as query.

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/mysafe/password/197, the API returns the data of the device whose identifier is 197.

{
    "code": 200,
    "response": {
        "status": 200,
        "message": "Success",
        "error": false,
        "error_code": 0,
        "detail": "",
        "mensagem": "Success",
        "erro": false,
        "cod_erro": 0
    },
    "password_entity": {
        "identifier": "197",
        "name": "Testing",
        "url": "www.url.com",
        "username": "maria",
        "password": "Cs^Q4PdbIOo4",
        "secret_key": JBSWY3DPEHPK3PXP,
        "token": 452180,
        "notes": "This is a test password",
        "tags": "test",
        "users_allowed": [],
        "groups_allowed": []
    }
}

Each document contains the description of the response body fields.
Access the document GET | List a password by [identifier] 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.

CodeResponse
2xxSuccessful responses that do not require any action from the user.
4xxError responses caused by the absence of a required parameter, for example, and that require corrective action from the user.
5xxErrors from the senhasegura server that suggest corrective action from the server.

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

{
    "response": {
        "status": 400,
        "mensagem": "1005: Password not found",
        "erro": true,
        "cod_erro": 0,
        "message": "1005: Password not found",
        "error": true,
        "error_code": 0
    },
    "exception": {
        "code": 1005,
        "message": "1005: Password not found",
        "detail": ""
    }
}

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

Access the following documents for more detailed information and examples:


Was this article helpful?

What's Next