Authentication and Authorization

All calls to Mira APIs must be authenticated and authorized. There are two methods of authenticating.

Access Tokens

curl -X POST https://api.mira.co/user/me/ \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c'

The preferred method of authentication is to present a Bearer access token in the Authorization header of all requests (see aside). Access tokens are JWTs, which consist of a header, payload, and cryptographic signature. The payload contains identifying information that is used to determine your access to different API resources, such as a list of scopes your user ID.

Refresh Tokens (API Keys)

curl -X POST https://api.mira.co/user/me/ \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Refresh FmfDZSdAeKLj_ZnBAAZjXNln78SMXY5Hlssqg0pJ-AcGG'

Alternatively, users may create an refresh token (essentially an API Key) and present that in the Authorization header with the Refresh scheme. These are secret keys that are used to fetch access tokens on the backend.

Token Creation

For security reasons, tokens must be fetched through a web flow. This is not an issue if you are interacting with our API through the Mira console. However, if you are planning on accessing our API programmatically, you must use the refresh token method, and you must generate the token for the first time through the dedicated application.

In order to generate a refresh token, visit https://token.mira.co, sign in with a valid user/password, and generate a new code. All other refresh tokens will be revoked upon generation of a new token.

Note: you may be instructed to visit a testing tenant, such as https://dev-token.mira.co. Consult your account rep.

Scoped Authorization

In addition to being authenticated, users must be authorized to perform certain actions. For example, to create a new POI, users must have the write:pois scope. This is distinct from being authorized to read/write specific resources, which we explain in the user section.

Each sub-API has its own set of scopes which will be enumerated in the corresponding documentation.