# Model access and publishing API (/docs/ai/model-as-a-service/model-access-api)



Every model that the BSQAI API serves is a serving endpoint, identified by the ID of its model route. This page is for AI engineers and administrators who manage model access with the API. [Model access](/docs/use/portal/ai-hub#model-access) in Studio describes the same rules in the Portal.

Two decisions control who may call a model:

* **Which tenants may use it.** A model serves its owning organization. A platform administrator decides which other tenants may use a Global model, and a tenant's administrators decide whether to publish their tenant's language models to every tenant.
* **Who in a tenant may call it.** Each tenant sets allow rules on the models offered to it. Without a rule, nobody in the tenant can call the model, except the model's owner in its own tenant.

## Before you begin [#before-you-begin]

Authenticate with a platform token or a BSQAI API key, sent as `Authorization: Bearer ...`. Every call acts in the caller's active tenant: an API key carries its tenant, and a token that belongs to more than one organization also sends `X-Tenant-Id`.

```bash
export BSQAI_API="https://<bsqai-api-host>"
export TOKEN="<access-token-or-api-key>"
```

| Task                                                         | Permission                                                                                                                                                                                                                                                | Who has it                                                       |
| ------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------- |
| List the models you see                                      | `tenant.read`                                                                                                                                                                                                                                             | Every member                                                     |
| List a model's allow rules, and its Owner and Grant Managers | [`authorization.resource_grant.list`](/docs/reference/roles-permissions/authorization#authorizationresource_grantlist)                                                                                                                                    | Every member                                                     |
| Add or remove an allow rule, a Grant Manager, or an Owner    | [`authorization.resource_grant.create`](/docs/reference/roles-permissions/authorization#authorizationresource_grantcreate) and [`authorization.resource_grant.revoke`](/docs/reference/roles-permissions/authorization#authorizationresource_grantrevoke) | Every member                                                     |
| Publish or unpublish a model the tenant owns                 | `inference.endpoint.publish`                                                                                                                                                                                                                              | Tenant Administrators. It cannot be given through a custom role. |
| Let a tenant publish its models                              | Platform administrator                                                                                                                                                                                                                                    | Platform administrators                                          |
| Choose which tenants may use a model                         | `platform.global_service.manage` in the Global organization                                                                                                                                                                                               | Platform administrators                                          |

The permission is the operation gate. Whether the call succeeds also depends on the caller's place on the model: only the people who manage a model's rules may change them. They are:

* in a customer organization, its Tenant Administrators, for every model that the Global organization or another tenant offers to it;
* in the Global organization, platform administrators;
* in the organization that owns a model, its Owner and Grant Managers. That organization's Tenant Administrators do not manage the rules of its own models: they can only assign a new Owner when the Owner has left.

A caller who may see the model but not change it gets 403 `permission_denied`. A caller who may not see it gets 404 `serving_endpoint_not_found`, so probing for IDs reveals nothing.

## List the models you see [#list-the-models-you-see]

`GET /v1/serving-endpoints` lists the models the caller sees in the active tenant: every model the tenant owns, and every other model the tenant holds a rule on. Each entry of the response's `endpoints` list has these fields:

```bash
curl -sS "$BSQAI_API/v1/serving-endpoints" -H "Authorization: Bearer $TOKEN"
```

| Field                                  | Meaning                                                                                                                              |
| -------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------ |
| `id`                                   | The serving endpoint ID, the model route's ID. The Model Installer reports it as `route_id`.                                         |
| `alias`                                | The model name that callers send                                                                                                     |
| `mode`                                 | `chat`, `embedding`, `rerank`, `predictive`, or `unknown`                                                                            |
| `global_owned`, `owned_by_this_tenant` | Whether the Global organization or the active tenant owns the model                                                                  |
| `audience`                             | Which tenants besides its owner may use it: `owner`, `everyone`, or `listed`                                                         |
| `can_invoke`                           | Whether the caller may call the model                                                                                                |
| `can_view`                             | Whether the caller sees the model                                                                                                    |
| `can_manage_access`                    | Whether the caller may list and change the tenant's rules on it                                                                      |
| `can_publish`                          | Whether the caller may publish or unpublish it                                                                                       |
| `can_operate`                          | Whether the caller is an Inference Operator of the owning tenant, who sees its Owner, Grant Managers and rules without changing them |
| `can_assign_owner`                     | Whether the caller may assign a new Owner, because the Owner left the tenant                                                         |

## Manage allow rules [#manage-allow-rules]

An allow rule lets a user, a group, or All Members of the active tenant call a model there. A rule applies only in the tenant where it was set.

| Method | Path                                       | Use                                                              |
| ------ | ------------------------------------------ | ---------------------------------------------------------------- |
| `GET`  | `/v1/serving-endpoints/{id}/grants`        | List the tenant's rules on the model                             |
| `POST` | `/v1/serving-endpoints/{id}/grants`        | Add a rule                                                       |
| `POST` | `/v1/serving-endpoints/{id}/grants/revoke` | Remove a rule. Removing one that does not exist changes nothing. |

```bash
curl -sS -X POST "$BSQAI_API/v1/serving-endpoints/<endpoint-id>/grants" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"subject_type": "group", "subject_id": "<group-uuid>", "relation": "invoker"}'
```

`subject_type` is `user`, `group`, or `all_members`. `subject_id` names the user or group and is omitted for All Members. The user or group must belong to the tenant. `relation` is `invoker`, which lets the subject call the model.

A new `viewer` rule is refused with 400 `serving_endpoint_viewer_rule_retired`, because every member already sees the models their tenant owns or allows. A `viewer` rule made earlier is still listed and can be removed. A rule that would let nobody call the model who cannot already is refused with 409 `serving_endpoint_grant_changes_nothing`: a rule that exists, a rule for the model's owner, or any other rule while All Members may call it.

Removing a rule stops new calls at once. Work already running, such as a Deep Research run, finishes with its model.

## Publish a tenant's model [#publish-a-tenants-model]

A tenant's language model serves only that tenant until it is published. Publishing offers it to every tenant, and each tenant then decides with its own rules which of its members may call it. The owning tenant keeps running and paying for the model. Other tenants see the model, never its deployment.

A platform administrator first lets the tenant publish:

```bash
curl -sS -X PUT "$BSQAI_API/v1/admin/tenants/<lifecycle-id>/inference/publishing" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"enabled": true}'
```

The tenant's response reports `inference_publishing`. Sending `{"enabled": false}` unpublishes every model that the tenant published. Other tenants' rules on them stay, and apply again if the models are published again. In the Portal, this is **Let this tenant publish its models** under **Publishing to all tenants**, on the tenant's **Deployment policy** tab in **Administration**. See [Let a tenant publish its models](/docs/administration#let-a-tenant-publish-its-models).

A Tenant Administrator of the owning tenant then publishes one model:

```bash
curl -sS -X PUT "$BSQAI_API/v1/serving-endpoints/<endpoint-id>/publication" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"published": true}'
```

`{"published": false}` unpublishes it. Unpublishing does not need the tenant's permission to publish. In the Portal, this is **Publish to all tenants** under **Access** on the model.

| Status | Code                                        | Cause                                                                                    |
| ------ | ------------------------------------------- | ---------------------------------------------------------------------------------------- |
| 409    | `serving_endpoint_publishing_disabled`      | A platform administrator has not let the tenant publish its models.                      |
| 409    | `serving_endpoint_not_publishable`          | The model is a predictive model. Only language models are published.                     |
| 409    | `serving_endpoint_audience_set_by_platform` | The model is a Global model, or a platform administrator chose which tenants may use it. |
| 403    | `permission_denied`                         | Another tenant owns the model.                                                           |

## Choose which tenants may use a model [#choose-which-tenants-may-use-a-model]

A platform administrator sets a model's audience with `PUT /v1/admin/model-routes/{id}/audience`:

```bash
curl -sS -X PUT "$BSQAI_API/v1/admin/model-routes/<route-id>/audience" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"audience": "listed", "tenant_ids": ["<tenant-organization-uuid>"]}'
```

| `audience` | Who may use the model besides its owner                                                |
| ---------- | -------------------------------------------------------------------------------------- |
| `everyone` | Every tenant                                                                           |
| `listed`   | Only the tenants in `tenant_ids`, which is required for this value and empty otherwise |
| `owner`    | Nobody                                                                                 |

A Global model takes any audience, including a model that the Model Installer deployed. A tenant's model reaches other tenants only after its owner publishes it. A platform administrator can then narrow it to chosen tenants, open it to every tenant again, or unpublish it with `owner`. The deployment keeps running in every case. Each tenant still decides with its own rules which of its members may call the model.

The response is the route, with `owner_tenant_id`, `audience`, and `audience_tenant_ids`. In the Portal, this is the **Who may use it** column under **Model routing** in Studio, changed with the people button at the end of the route's row, with the choices **All tenants**, **Chosen tenants**, and **Owner only**.

| Status | Code                                       | Cause                                                |
| ------ | ------------------------------------------ | ---------------------------------------------------- |
| 400    | `serving_endpoint_audience_tenant_unknown` | A tenant in `tenant_ids` does not exist.             |
| 409    | `serving_endpoint_not_published`           | The tenant that owns the model has not published it. |
| 409    | `serving_endpoint_not_publishable`         | The tenant's model is a predictive model.            |

## Owner and Grant Managers [#owner-and-grant-managers]

In a customer organization, the person who deploys a model becomes its Owner. The Owner calls the model without a rule and names the Grant Managers, users or groups of the tenant who manage the model's rules with the Owner. A Global model has neither, and these routes answer 409 `serving_endpoint_global_owned` for it. Only the tenant that owns a model reaches them.

| Method | Path                                               | Use                                                                                                                                                                            |
| ------ | -------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `GET`  | `/v1/serving-endpoints/{id}/stewardship`           | Read the model's Owner and Grant Managers, and what the caller may change. For the Owner, Grant Managers, Inference Operators, and Tenant Administrators of the owning tenant. |
| `POST` | `/v1/serving-endpoints/{id}/grant-managers`        | Name a Grant Manager: `{"subject_type": "user" or "group", "subject_id": "<uuid>"}`. Owner only.                                                                               |
| `POST` | `/v1/serving-endpoints/{id}/grant-managers/revoke` | Remove a Grant Manager, with the same body. Owner only.                                                                                                                        |
| `PUT`  | `/v1/serving-endpoints/{id}/owner`                 | Assign a current member as Owner: `{"user_id": "<uuid>"}`. Tenant Administrators only, and only after the Owner left the tenant.                                               |

The stewardship response lists `owners`, each with `user_id` and `is_member`, and `grant_managers`. `needs_owner` is `true` when no Owner is still a member of the tenant. An Owner who left manages nothing. Assigning a new Owner while the Owner is still a member answers 409 `serving_endpoint_owner_still_member`.

A Grant Manager or Owner change on a model applies to its LoRA adapters too.

## Related pages [#related-pages]

* [Model Installer API](/docs/ai/model-as-a-service/model-installer-api)
* [Cloud and external models](/docs/ai/model-as-a-service/cloud-models)
* [Inference permissions](/docs/reference/roles-permissions/inference)
* [Set what a tenant may deploy](/docs/administration#set-what-a-tenant-may-deploy)
