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

# Partner API credentials

> Create, scope, rotate, and revoke credentials for third-party REST access.

Partner API credentials are the credential for a third-party system that calls
Casa on behalf of one organization. You create them in the app. The partner
stores the client id and secret, then exchanges them for a short-lived access
token.

Use [personal API keys](/api-keys) for first-party scripts and MCP clients. Do
not use a partner credential for the [MCP server](/mcp-server) or a human CLI.

<Note>
  A partner credential is org-scoped and REST-only. The same vendor at two
  hotels needs two credentials. Casa never stores the plaintext client secret.
</Note>

## Creating credentials

1. In the Casa app, open **Integrations**.
2. Go to **Partner credentials**.
3. Open **Custom Integration**.
4. On the **Overview** tab, enter a name (for example *AI Agent*) and an optional description.
5. Select at least one read scope.
6. Click **Create credentials**.
7. Copy the **client id** and **client secret**.

<Warning>
  The client secret is shown **once**. Casa does not store the plaintext secret.
  If you lose it, rotate the credentials and store the new secret.
</Warning>

## What credentials can do

Partner credentials are **read-only** and **group-scoped**. They cannot pin to
one property. They cannot send `X-Property-Id`. They cannot call MCP.

Pick at least one scope from this list. Casa rejects writes,
`read:integrations`, and `*`.

| Scope               | Grants                                                  |
| ------------------- | ------------------------------------------------------- |
| `read:guests`       | Guest profiles and master profiles                      |
| `read:reservations` | Reservation search                                      |
| `read:transactions` | Transaction search                                      |
| `read:consents`     | Consent observation search                              |
| `read:actions`      | Guest actions                                           |
| `read:events`       | The guest event log                                     |
| `read:reviews`      | Review search and the reviews summary                   |
| `read:loyalty`      | Loyalty programs and member search                      |
| `read:channels`     | Booking channels                                        |
| `read:spaces`       | Bookable spaces                                         |
| `read:properties`   | The group's property roster                             |
| `read:sql`          | Read-only SQL over the public data model                |
| `read:tables`       | Table list, detail, members, filters, preview, and runs |

See the full [scope table](/authentication#scopes) for session-only scopes.

Any member of your organization can create and revoke the group's partner
credentials. A credential only grants the read scopes you selected.

## Get an access token

Post `client_credentials` to the Casa token endpoint. Use HTTP Basic or
`client_secret_post`.

```bash theme={null}
curl -X POST https://temperate-milestone-52.authkit.app/oauth2/token \
  -u "$CLIENT_ID:$CLIENT_SECRET" \
  -d grant_type=client_credentials
```

```json theme={null}
{
  "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "Bearer",
  "expires_in": 3600
}
```

Cache the access token until `exp`. Then request a new token. Do not mint a
token on every Casa call.

## Call the REST API

Send the access token as a bearer credential. Do not send `X-Property-Id`.

```bash theme={null}
curl https://api.casa-layer.com/v1/guests \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

Casa verifies the token, maps it to the property group, and applies the scopes
from the credential. The MCP server rejects these tokens. Use a
[personal API key](/api-keys) or [Casa sign-in](/mcp-server#claude-oauth) for
assistants.

## Rotate, revoke, and change scopes

Manage existing credentials on **Integrations → Custom Integration →
Configuration**. Each credential shows its scopes, creator, created date, and
last-used time when the issuer reports one.

* **Edit scopes** replaces the grant. Pick at least one read scope from the
  allowlist.
* **Rotate** issues a new client secret and deletes the old one. Store the new
  secret with the partner. The client id stays the same.
* **Revoke** marks the credential revoked. The next Casa request for that
  client id returns `401`.

A leftover access token may still work until `exp` (**up to 3600 seconds**).
Casa does not keep a token denylist. Revoke still blocks the next resolve.

## Isolation

One credential binds to one Casa organization. Hotel A and hotel B each create
their own client id. A's token cannot read B's guests.

## Good practice

* **One credential per consumer.** Name it after the system that will use it
  so revocation is surgical.
* **Grant the fewest scopes.** Select only the read scopes the partner needs.
* **Cache the access token.** Reuse it until `exp`. Then request a new token.
* **Rotate by overlap.** Issue a new secret, deploy it, then stop the old one.
* **Keep secrets out of source control.** Inject them with environment
  variables or your secret manager.