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

# Consumer API

> Reference for the XCS Consumer API v1 — endpoints, authentication, error codes, and usage examples.

The Consumer API provides programmatic access to XCS access control features. It is designed for automated systems that need to interact with the platform without a browser-based session.

## Base URL

```
https://api.restrafes.co/api/consumer/v1
```

## Authentication

All Consumer API requests require an API key passed in the `X-API-Key` header:

```bash theme={null}
curl -H "X-API-Key: your-api-key-here" \
  https://api.restrafes.co/api/consumer/v1/
```

Organization API keys are generated from the organization management page on the XCS dashboard. The API key must be authorized for the organization and resource you are trying to access.

<Callout type="warning">
  Keep your API key secure. Do not share it in client-side code, version control, or public channels. If a key is compromised, revoke it from the dashboard and generate a new one.
</Callout>

## Endpoints

| Method | Path                                | Description                                    |
| ------ | ----------------------------------- | ---------------------------------------------- |
| GET    | `/`                                 | Root health check — returns API status         |
| GET    | `/ping`                             | Ping with version information                  |
| GET    | `/organizations`                    | List organizations authorized for this API key |
| POST   | `/access-points/{id}/remote-unlock` | Trigger a remote unlock on an access point     |

## Health Check

Verify that the API is reachable and your API key is valid.

```bash theme={null}
curl -H "X-API-Key: your-api-key-here" \
  https://api.restrafes.co/api/consumer/v1/
```

**Example response:**

```json theme={null}
{
  "status": "ok",
  "service": "consumer-api"
}
```

## Ping

Check API version and connectivity.

```bash theme={null}
curl -H "X-API-Key: your-api-key-here" \
  https://api.restrafes.co/api/consumer/v1/ping
```

**Example response:**

```json theme={null}
{
  "status": "ok",
  "version": "2.0.0"
}
```

## List Organizations

Retrieve the organizations that your API key is authorized to access.

```bash theme={null}
curl -H "X-API-Key: your-api-key-here" \
  https://api.restrafes.co/api/consumer/v1/organizations
```

**Example response:**

```json theme={null}
[
  {
    "id": "org-uuid-here",
    "name": "My Studio",
    "role": "owner"
  }
]
```

## Remote Unlock

See the [Remote Unlock](/api/remote-unlock) page for the complete reference, including request parameters, scope options, error handling, and the Roblox MessagingService integration.

## Error Response Format

When an API request fails, the response includes:

```json theme={null}
{
  "error": "Description of what went wrong"
}
```

Some error responses also include a `requestId` field for debugging.

### Common HTTP Status Codes

| Code | Meaning                                                                        |
| ---- | ------------------------------------------------------------------------------ |
| 200  | Success                                                                        |
| 400  | Bad request -- invalid parameters or missing required fields                   |
| 401  | Unauthorized -- invalid or missing API key                                     |
| 403  | Forbidden -- API key not authorized for this resource                          |
| 404  | Resource not found                                                             |
| 422  | Unprocessable entity -- configuration issue (e.g., missing Roblox Universe ID) |
| 429  | Too many requests -- rate limit exceeded                                       |
| 502  | Bad gateway -- upstream service error (e.g., Roblox MessagingService failure)  |
| 504  | Gateway timeout -- upstream service did not respond in time                    |