---
title: "First steps"
slug: "api-mysafe-first-steps"
updated: 2026-11-03T14:48:14Z
published: 2026-11-03T14:48:14Z
canonical: "docs.senhasegura.io/api-mysafe-first-steps"
---

> ## Documentation Index
> Fetch the complete documentation index at: https://docs.senhasegura.io/llms.txt
> Use this file to discover all available pages before exploring further.

# 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.
- Application and authorization for the application created in **MySafe**. Access the document on  [Access keys](/v4-2/docs/mysafe-access-keys-screen) for more information.

---

## 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 [Access keys](/v4-2/docs/mysafe-access-keys-screen) 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` `{{Segura}}/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, Segura™ 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 Segura™ instance. For example, for the tenant `test` accessed via `test.Segura.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 Segura™'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]](/v4-2/docs/api-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.

| Code | Response |
| --- | --- |
| **2xx** | Successful responses that do not require any action from the user. |
| **4xx** | Error responses caused by the absence of a required parameter, for example, and that require corrective action from the user. |
| **5xx** | Errors from the Segura™ 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.

## Links to MySafe API documentation

Access the following documents for more detailed information and examples:

- [Passwords](/v4-2/docs/api-mysafe-passwords).
- [Notes](/v4-2/docs/api-mysafe-notes).
- [API secrets](/v4-2/docs/api-mysafe-api-secrets).