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

# Authentication

> PMS credentials: format, environments, safe storage, rotation and revocation.

Every request except `GET /v1/health` carries your PMS credential as a Bearer token:

```http theme={null}
GET /v1/me HTTP/1.1
Host: staging.api.tatallo.com
Authorization: Bearer tat_stg_sk_<credential-id>_<secret>
```

There is no token exchange and nothing to refresh: the key itself is the credential. A key may carry an expiry date, which Tatallo tells you when it issues the key.

## Key format and environments

A PMS credential is an opaque string issued by Tatallo. Its prefix names the environment it belongs to:

| Prefix | Environment | Base URL |
| - | - | - |
| `tat_stg_sk_` | Staging | `https://staging.api.tatallo.com` |
| `tat_live_sk_` | Production | `https://api.tatallo.com` |

A key works only in its own environment. A staging key sent to production gets `401`, and so does a production key sent to staging, so test traffic can never reach live data. Treat the rest of the key as opaque: don't parse it.

## Keep keys on your servers

* Call the Tatallo PMS API **server to server only**. Never ship a key to a browser, a mobile app or any other client.
* Keep keys in your secrets manager, not in source code or configuration files.
* **Never log a key**, and never log the `Authorization` header. `GET /v1/me` never returns a secret, so logging its response is safe.
* If a key may have leaked, tell [developers@tatallo.com](mailto:developers@tatallo.com) at once. Tatallo revokes it immediately.

## Rotation and revocation

Ask [developers@tatallo.com](mailto:developers@tatallo.com) to rotate a key. Tatallo issues the new key first, through a one-time secret link. You switch your servers to it, and Tatallo revokes the old key only once it sees calls with the new one, so there is no downtime.

A revoked or expired key gets `401` from its next request.

## 401 or 403?

| Status | Code | What it means | What to do |
| - | - | - | - |
| `401` | `unauthorized` | The key is missing, malformed, for the other environment, expired or revoked. All of these get the same answer, on purpose. | Check the header, the prefix against the base URL, and that the key is current. |
| `403` | `insufficient_scope` | The key is valid but lacks the scope the route needs (`properties:read` for properties). | Ask for a key with that scope. |

`GET /v1/me` shows the scopes of the key you are using.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.