AimableDocs
DocsAPI ReferenceRelease Notes

Provisioning

DeveloperUpdated 9 July 2026

Overview

This page walks through setting up one space end to end: create the space, set its model policy, create a service principal, grant it access to the space, and mint an API key its integration will use. All of these run under your tenant-admin credentials.

Throughout, $ADMIN is a tenant-admin credential (API key or bearer token) and $BASE is your per-tenant gateway base — https://<your-tenant>.aimable.ai/api.

1. Create a space

A space is your unit of isolation — create one for whatever you want to keep separate (a customer, an environment, an application — your choice).

bash
curl -X POST "$BASE/v1/spaces" \
  -H "X-API-Key: $ADMIN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Production",
    "description": "Production workspace",
    "apply_pii_pseudonymization": false
  }'

The response returns the new space inside a data envelope: { "data": { "id": "<uuid>", ... } }. Keep that id — it is the space_id that requests to this space carry in the X-Aimable-Space-Id header.

2. Set the space's model policy

Decide which models the space may use and which is the default. The policy mode is one of fixed (only the default), user_select (a curated allow-list), or auto (reserved for policy-driven routing — currently resolves to the default model).

The model ids used here are tenant model ids — list them with GET /v1/tenant/models and use each entry's id. (These differ from the catalog ids returned by GET /v1/models.)

bash
curl -X PUT "$BASE/v1/spaces/$SPACE_ID/model-policy" \
  -H "X-API-Key: $ADMIN" \
  -H "Content-Type: application/json" \
  -d '{
    "mode": "fixed",
    "default_model_id": "<tenant_model_id>"
  }'

To offer more than one model, set mode to user_select and add models to the allow-list:

bash
curl -X POST "$BASE/v1/spaces/$SPACE_ID/models" \
  -H "X-API-Key: $ADMIN" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{ "tenant_model_id": "<tenant_model_id>" }'

See Space model policy and Space allowed models for the full model.

3. Create a service principal

A service principal is a non-human identity that owns the API key your backend uses.

bash
curl -X POST "$BASE/v1/admin/principals" \
  -H "X-API-Key: $ADMIN" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "service",
    "name": "Backend service"
  }'

The response returns the new principal inside a data envelope: { "data": { "id": "<uuid>", "type": "service", ... } }. Use that id as the principal_id in the steps below.

4. Grant the principal access to the space

Add the principal as a member of the space, then assign it a role.

bash
curl -X POST "$BASE/v1/spaces/$SPACE_ID/members" \
  -H "X-API-Key: $ADMIN" \
  -H "Content-Type: application/json" \
  -d '{ "principal_id": "<principal_id>" }'
 
curl -X POST "$BASE/v1/spaces/$SPACE_ID/members/<principal_id>/roles" \
  -H "X-API-Key: $ADMIN" \
  -H "Content-Type: application/json" \
  -d '{ "role_key": "member" }'

List a space's roles with GET /v1/spaces/{space_id}/roles. You can assign by role_id or by the built-in role_key. For a service principal that only needs to run inference, member is sufficient — it grants chat invocation. See Space roles for all roles and the permissions each grants.

5. Mint an API key

Create the key on the service principal. The plaintext key is returned once — store it securely and never log it.

bash
curl -X POST "$BASE/v1/admin/principals/<principal_id>/api-keys" \
  -H "X-API-Key: $ADMIN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Production key",
    "expires_at": null
  }'

Response (shown only at creation):

json
{
  "data": {
    "key": "ak.AbC123.s3cr3t...",
    "key_id": "AbC123",
    "name": "Production key",
    "expires_at": null,
    "created_at": "2026-01-01T00:00:00Z"
  }
}

The key value is what the integration sends in X-API-Key.

6. Make a call

With the key and the space id, the integration calls inference exactly as in Getting Started:

bash
curl -X POST "$BASE/v1/chat/completions" \
  -H "X-API-Key: ak.AbC123.s3cr3t..." \
  -H "X-Aimable-Space-Id: $SPACE_ID" \
  -H "Content-Type: application/json" \
  -d '{ "messages": [{ "role": "user", "content": "Hello!" }] }'

Managing keys

  • List keys for a principal: GET /v1/admin/principals/{principal_id}/api-keys (never returns the plaintext).
  • Rotate a key: POST /v1/admin/principals/{principal_id}/api-keys/{key_id}/rotate (returns a new plaintext, invalidates the old secret).
  • Revoke a key: POST /v1/admin/principals/{principal_id}/api-keys/{key_id}/revoke.

Rotate on a schedule and revoke immediately if a key is exposed.

Next steps