# ModelCredential

A tenant's own credential for a model provider (collection `modelCredential`). It holds:

- a provider;
- its keys, tried in order;
- the models it may serve, with any deployment names;
- an optional endpoint (none means the provider's public API);
- an optional tag for grouping.

Runs never name a credential directly: they use a `CredentialStack` of them.

Secrets are write-only. They're accepted on create and update and never served, and only `ModelCredentialKey.KeyHint` identifies a key. A credential belongs to one tenant: every lookup is by tenant, and another tenant's id reads as not found.

**Kind:** an object, used in responses.

## Fields

Every field is present in a response; empty ones are `null`.

| Field | Type | Description |
|---|---|---|
| `name` | `string` | Unique within the tenant. |
| `description` | `string \| null` |  |
| `provider` | [`ModelKeyProvider`](https://docs.maitento.com/reference/types/model-key-provider.md) |  |
| `kind` | [`CredentialKind`](https://docs.maitento.com/reference/types/credential-kind.md) |  |
| `endpoint` | `string \| null` | The endpoint to call; null for the provider's public API. Always HTTPS on the public internet. |
| `endpointKind` | [`CredentialEndpointKind`](https://docs.maitento.com/reference/types/credential-endpoint-kind.md) | Worked out from `ModelCredential.Provider`, `ModelCredential.Endpoint` and `ModelCredential.Cloud` when the credential is saved. |
| `cloud` | [`CredentialCloud`](https://docs.maitento.com/reference/types/credential-cloud.md)`\| null` | For an Anthropic credential, Claude on Amazon Bedrock or Google Vertex AI instead of Anthropic's API (with no `ModelCredential.Endpoint`). Null for every other credential. |
| `keys` | [`ModelCredentialKey`](https://docs.maitento.com/reference/types/model-credential-key.md)`[]` |  |
| `oAuth` | [`ModelCredentialOAuth`](https://docs.maitento.com/reference/types/model-credential-o-auth.md)`\| null` | The subscription sign-in of an OAuth credential; null for an API-key credential, which has `ModelCredential.Keys` instead. |
| `models` | [`CredentialModel`](https://docs.maitento.com/reference/types/credential-model.md)`[]` | The models it may serve; empty for any of the provider's models. |
| `tag` | `string \| null` | A label for grouping, such as one caller's customer; credentials can be listed and deleted by tag. |
| `externalTenantRef` | `string \| null` | The tenant in the calling system that owns this credential, as `<system>:<id>`; null when the owner isn't known. Set once, when the credential is created, and never changed. |
| `health` | [`CredentialHealth`](https://docs.maitento.com/reference/types/credential-health.md) |  |
| `createdByUserId` | `uuid \| null` |  |
| `revision` | `integer` | Goes up by one each time the credential is changed: edited, signed in again, or its tokens refreshed. |
| `tenantId` | `uuid` | The id of the tenant it belongs to. |
| `id` | `uuid` | The unique id. Use it in `by-id` routes and wherever another object refers to this one. |
| `dateCreated` | `datetime` | When it was created, in UTC. |
| `dateUpdated` | `datetime` | When it was last changed, in UTC. |

## Example

```json
{
  "name": "...",
  "description": "...",
  "provider": "Anthropic",
  "kind": "ApiKey",
  "endpoint": "...",
  "endpointKind": "Public",
  "cloud": {
    "kind": "Bedrock",
    "awsRegion": "...",
    "gcpProjectId": "...",
    "gcpRegion": "..."
  },
  "keys": [
    {
      "id": "3f2b8c1e-5d4a-4e6b-9c7d-2a1b0c9d8e7f",
      "keyHint": "...",
      "addedAtUtc": "2026-10-26T12:00:00.0000000Z"
    }
  ],
  "oAuth": {
    "tool": "Claude",
    "expiresAtUtc": "2026-10-26T12:00:00.0000000Z",
    "scopes": [
      "..."
    ],
    "subscriptionType": "...",
    "accountName": "...",
    "signedInAtUtc": "2026-10-26T12:00:00.0000000Z",
    "refreshedAtUtc": "2026-10-26T12:00:00.0000000Z",
    "nextRefreshAtUtc": "2026-10-26T12:00:00.0000000Z",
    "refreshedByCaller": false,
    "refreshFailures": 0,
    "lastRefreshError": "..."
  },
  "models": [
    {
      "model": "...",
      "deploymentName": "...",
      "contextWindowTokens": 0
    }
  ],
  "tag": "...",
  "externalTenantRef": "...",
  "health": {
    "consecutiveFailures": 0,
    "disabledUntilUtc": "2026-10-26T12:00:00.0000000Z",
    "breaks": 0,
    "offUntilTested": false,
    "lastFailureAtUtc": "2026-10-26T12:00:00.0000000Z",
    "lastFailureReason": "...",
    "lastTestedAtUtc": "2026-10-26T12:00:00.0000000Z",
    "lastTestSucceeded": false,
    "lastTestError": "..."
  },
  "createdByUserId": "3f2b8c1e-5d4a-4e6b-9c7d-2a1b0c9d8e7f",
  "revision": 0,
  "tenantId": "3f2b8c1e-5d4a-4e6b-9c7d-2a1b0c9d8e7f",
  "id": "3f2b8c1e-5d4a-4e6b-9c7d-2a1b0c9d8e7f",
  "dateCreated": "2026-10-26T12:00:00.0000000Z",
  "dateUpdated": "2026-10-26T12:00:00.0000000Z"
}
```

## Where it's used

- [`credentials.create`](https://docs.maitento.com/reference/api/credentials.md) (`POST /credentials`)
- [`credentials.get`](https://docs.maitento.com/reference/api/credentials.md) (`GET /credentials/by-id/{id}`)
- [`credentials.importSignIn`](https://docs.maitento.com/reference/api/credentials.md) (`POST /credentials/sign-in-tokens`)
- [`credentials.list`](https://docs.maitento.com/reference/api/credentials.md) (`GET /credentials`)
- [`credentials.replaceSignInTokens`](https://docs.maitento.com/reference/api/credentials.md) (`PUT /credentials/by-id/{id}/sign-in-tokens`)
- [`credentials.update`](https://docs.maitento.com/reference/api/credentials.md) (`PUT /credentials/by-id/{id}`)
- Inside [`CredentialSignInResult`](https://docs.maitento.com/reference/types/credential-sign-in-result.md)