---
title: 'REST API: Tenants'
path: reference/rest-api/tenants
status: published
---

# REST API: Tenants

Per-tenant ScaiGrid credential management. One status endpoint, one mutator.

All endpoints under `/api/v1/tenants/me` — the caller's tenant is always derived from their ScaiKey JWT.

## `GET /v1/tenants/me/scaigrid_credentials`

Returns the configured status of the tenant's ScaiGrid credentials.

**Response:**

```jsonc
{
  "configured": true,
  "base_url": "https://scaigrid.scailabs.ai",
  "masked_key": "sgk_…1234"      // first 4 + last 4 chars
}
```

If no credentials are set, returns:

```jsonc
{
  "configured": false,
  "base_url": null,
  "masked_key": null
}
```

No special permission required — any tenant member can see whether their tenant has credentials configured.

## `POST /v1/tenants/me/scaigrid_credentials`

Set or rotate the tenant's ScaiGrid credentials. Written to ScaiVault at `tenants/{tenant_id}/scaigrid_api_key` and `tenants/{tenant_id}/scaigrid_base_url`.

**Body:**

```jsonc
{
  "api_key": "sgk_xxxxxxxxxxxx",
  "base_url": "https://scaigrid.scailabs.ai"          // optional
}
```

**Response:** `204 No Content`.

`tenant_admin` or `super_admin` required.

## Why this exists

The backend can authenticate to ScaiGrid in two ways:

1. **User JWT** (preferred) — when there's a calling user, forward their ScaiKey access token. ScaiGrid accepts it directly.
2. **Per-tenant API key** (fallback) — when there's no user (background sync, scheduled triggers, dev-token deploys), the backend looks up the tenant's `sgk_*` key from ScaiVault.

For most tenant operations the user-JWT path is enough. But some flows need the API-key fallback to be configured:

- The background ScaiKey-sync loop.
- Cron-triggered flows whose entry node is `entry_schedule`.
- Dev environments where the ScaiFlow API runs without a real user session.

The `SCAIFLOW_DEPLOY_AUTH=user_jwt|api_key` env var pins the choice for debugging — leave it unset for default precedence (JWT, then API key).

## What the canvas does with this

The toolbar's status indicator + the tenant admin's Settings page both call `GET .../scaigrid_credentials`. If `configured: false`, the canvas shows a warning + a button that opens the credential entry form.

Setting the credentials there `POST`s to this endpoint — the API key isn't kept in the canvas's localStorage, just in ScaiVault.