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

# Machine credentials

> Run automation against the Admin API without a person re-issuing tokens: exchange a client ID and secret for a short-lived, gateway-scoped access token.

A console-minted admin JWT expires and nobody renews it, which is fine for a script you run
by hand and useless for automation that has to keep working next week. Machine credentials
solve that: your automation holds a long-lived `client_id` / `client_secret` pair and
exchanges it for a short-lived access token whenever it needs one.

Each credential is bound to **one gateway** and carries an explicit set of scopes. A
credential issued for gateway A cannot read or change anything in gateway B, even when both
belong to the same team.

<Note>
  Machine credentials are issued by the NeuralTrust platform (SaaS and Hybrid). Self-hosted
  open-source TrustGate has no credential store — mint admin JWTs yourself as described in
  [Server security](/trustgate/operate/server-security#admin-authentication).
</Note>

## Create a credential

In the console, open **Settings → Agent Gateway → Credentials**, click **New credential**,
name it after the system that will use it, and pick the scopes it needs.

The client secret is displayed **once**. Copy it into your secret manager before closing the
dialog — it is stored only as a hash and cannot be shown again. If you lose it, rotate the
credential to get a new one.

### Scopes

| Scope                                  | Grants                                                      |
| -------------------------------------- | ----------------------------------------------------------- |
| `gateways:read`                        | Read the bound gateway.                                     |
| `consumers:read` / `consumers:write`   | List and manage [consumers](/trustgate/concepts/consumers). |
| `auths:read` / `auths:write`           | Manage [auth credentials](/trustgate/concepts/auth).        |
| `roles:read` / `roles:write`           | Manage [roles](/trustgate/concepts/roles).                  |
| `registries:read` / `registries:write` | Manage [registries](/trustgate/concepts/registries).        |
| `policies:read` / `policies:write`     | Manage [policies](/trustgate/policies/overview).            |

Creating and deleting gateways stays a console-only operation. Grant the narrowest set that
makes your automation work.

## Exchange the credential for a token

The token endpoint implements the OAuth2 `client_credentials` grant. Credentials go in an
HTTP Basic header, or as form fields if your client cannot set one.

```bash theme={null}
curl -X POST https://app.neuraltrust.ai/api/gateway/oauth/token \
  -u "$CLIENT_ID:$CLIENT_SECRET" \
  -d grant_type=client_credentials
```

```json theme={null}
{
  "access_token": "eyJhbGciOiJSUzI1NiIsImtpZCI6...",
  "token_type": "Bearer",
  "expires_in": 300,
  "scope": "gateways:read consumers:read consumers:write"
}
```

Invalid credentials always return the same generic `invalid_client` error, so the endpoint
cannot be used to discover which client IDs exist.

## Call the Admin API

```bash theme={null}
curl https://<gateway-admin-host>/v1/gateways/$GATEWAY_ID/consumers \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

The token is valid for five minutes. Cache it and refresh on expiry (or on a `401`) rather
than minting one per request.

TrustGate rejects the request with `403` when the `gateway_id` in the path is not the
gateway the credential is bound to, or when the operation needs a scope the credential does
not hold. Reading a gateway that belongs to another tenant returns `404`, so the response
never reveals whether it exists.

## Rotate and revoke

**Rotate** issues a new secret and invalidates the old one immediately. Deploy the new
secret first if your automation cannot tolerate a failed token request; access tokens
already issued keep working until they expire.

**Revoke** stops new tokens from being issued at once. Because tokens live five minutes, a
revoked credential loses all access within that window — there is no remote introspection on
each admin request.

Both actions are recorded in the audit log, along with every token issued or denied, keyed
by credential ID. Secrets and tokens are never logged.