First steps

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

• MySafe administrator permission.

Create an application and an authorization

The creation of an application and its authorization to use the MySafe APIs is done directly in MySafe.

1. On senhasegura, in the upper-left corner, click the Grid Menu, represented by the nine squares, and select MySafe.
2. In the side menu, select Integrations > Access keys.
3. On the Access keys screen, click the View actions menu, represented by the three vertical dots icon, and select New.
4. Fill in the fields on the New access key screen and click Save.

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

Authenticate the application

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

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

6. 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.

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 MySafe APIs.

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.

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.

Links to MySafe API documentation

Access the following documents for more detailed information and examples:

• Passwords.

• Notes.

• API secrets.