---
title: Users and Access Reference
path: reference/users-and-access
status: published
---

# Users and Access Reference

User management, API keys, groups, custom roles, and group-to-role mappings. For concepts, see [Roles and Permissions](../03-core-concepts/02-roles-and-permissions.md).

## Users

### GET /v1/users

List users in the caller's tenant. Requires `users:manage`.

Query params: `limit`, `cursor`, `status` (`active` / `suspended`).

### GET /v1/users/{user_id}

Get a user's profile. Requires `users:manage` or the caller being the user themselves.

### PUT /v1/users/{user_id}/roles

Update a user's built-in roles.

```json
{"roles": ["tenant_user", "tenant_viewer"], "custom_role_ids": []}
```

Requires `users:manage`.

### GET /v1/users/{user_id}/module-permissions

List module permissions granted directly to the user (not through roles).

### PUT /v1/users/{user_id}/module-permissions

Grant or revoke direct module permissions.

```json
{"permissions": ["scaibot:bots:create", "scaimatrix:ingest"]}
```

Replaces the entire set. Requires `users:manage`.

### DELETE /v1/users/{user_id}

Soft-delete a user. Their API keys are revoked, their active sessions are killed. Requires `users:manage`.

### GET /v1/me

Get the current authenticated user's profile. Equivalent to `GET /v1/auth/me`.

## API keys

### GET /v1/api-keys

List API keys owned by the caller.

### POST /v1/api-keys

Create a new API key.

```bash
curl -X POST https://scaigrid.scailabs.ai/v1/api-keys \
  -H "Authorization: Bearer $TOKEN" \
  -d '{
    "name": "production-integration",
    "expires_at": "2027-04-22T00:00:00Z",
    "assigned_user_id": null
  }'
```

Response (shows the full key exactly once):

```json
{
  "data": {
    "id": "apikey_xyz",
    "name": "production-integration",
    "key": "sgk_full_key_here_shown_once",
    "prefix": "sgk_",
    "scopes": [...],
    "expires_at": "2027-04-22T00:00:00Z",
    "created_at": "2026-04-22T..."
  }
}
```

Subsequent GETs return metadata only — the database stores a SHA-256 hash, not the key.

### DELETE /v1/api-keys/{key_id}

Revoke an API key. Immediate effect. Requires `api_keys:manage`.

## Groups

Groups come from ScaiKey — you don't create them in ScaiGrid directly. ScaiGrid syncs them and lets you configure how they map to roles.

### GET /v1/groups

List groups synced from ScaiKey into the tenant.

### GET /v1/groups/{group_id}

Get a group's members and metadata.

## Role mappings

Role mappings tell ScaiGrid which ScaiKey group corresponds to which ScaiGrid role. When a user authenticates, their ScaiKey group memberships resolve to roles via these mappings.

### GET /v1/role-mappings

List all mappings for the tenant.

### POST /v1/role-mappings

Create a mapping.

```json
{
  "scaikey_group": "acme-engineers",
  "scaigrid_role": "tenant_user",
  "tenant_id": "tenant_acme",
  "auto_revoke": true
}
```

`auto_revoke: true` means a user removed from the ScaiKey group loses the role on next authentication.

### PUT /v1/role-mappings/{mapping_id}

Update a mapping.

### DELETE /v1/role-mappings/{mapping_id}

Remove a mapping. Users who had the role through this mapping lose it on next authentication.

## Custom roles

### GET /v1/custom-roles

List custom roles defined in the tenant.

### POST /v1/custom-roles

Create a custom role.

```json
{
  "name": "Analytics Team",
  "slug": "analytics",
  "description": "Read-only access to usage and export",
  "core_permissions": ["accounting:view_tenant", "models:list"],
  "module_permissions": []
}
```

### GET /v1/custom-roles/available-permissions

List all permissions available to assemble into custom roles. Both core permissions and module permissions from enabled modules.

### GET /v1/custom-roles/{role_id}

Get a custom role's definition.

### PUT /v1/custom-roles/{role_id}

Update a custom role's permission set, name, or description.

### DELETE /v1/custom-roles/{role_id}

Delete a custom role. Users who had it lose its permissions.

## Related

- [Roles and Permissions](../03-core-concepts/02-roles-and-permissions.md)
- [Custom Roles (advanced)](../07-advanced/04-custom-roles.md)
- [Authentication Reference](./01-authentication.md)