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

# Session environment, authorization and access grants

Use these operations to inspect effective environment values, compare pinned and current connection authorization, revoke a binding within one Session, or issue a scoped proxy credential. They do not edit a Session's pinned configuration or replace Provider credentials.

Paths include `/v1`. All operations enforce tenant ownership. The first three require owner identity; access-grant list/create/revoke also allow application tokens. Examples use a trusted backend token and `HEXAGON_API_URL` without `/v1`. Treat environment responses and issued tokens as private data.

## Read the effective environment

`GET /v1/sessions/{id}/environment` returns **200**, `{env:{...},scope:"agent_process",mutable:false}` and `Cache-Control:no-store`. It decrypts saved ordinary environment values; an empty environment returns `{}`. This is not the redacted initialization endpoint and is not a list of protected Provider/model secrets. There is no update operation here.

```sh theme={null}
umask 077
curl --fail-with-body --silent --show-error \
  -H "Authorization: Bearer $HEXAGON_API_TOKEN" --output session-environment.json \
  "$HEXAGON_API_URL/v1/sessions/$HEXAGON_SESSION_ID/environment"
```

Run in a private directory and check curl's exit status before reading the response; failed responses can also be saved. Prefer `/initialization` if you only need environment names and a historical configuration snapshot.

## Inspect current authorization

`GET /v1/sessions/{id}/authorization` returns **200**, `{session_id,connections:[...]}`. It evaluates currently stored connection/Secret/revocation state; it does not call providers or verify live credential validity.

```sh theme={null}
curl --fail-with-body --silent --show-error \
  -H "Authorization: Bearer $HEXAGON_API_TOKEN" \
  "$HEXAGON_API_URL/v1/sessions/$HEXAGON_SESSION_ID/authorization"
```

Each connection contains `id`, `name`, `kind`, `pinned_version`, `current_version`, nullable `secret:{id,name}`, `raw_secret_in_sandbox:false`, nullable `revoked_at` and `state`. Secret metadata does not include its value. State precedence is:

1. Session-specific revocation → revoked.
2. Deleted connection → deleted.
3. Disabled/not-ready connection, or disabled/deleted managed Secret → unavailable.
4. Non-Tool connection whose version differs from the pinned version → changed.
5. Otherwise → ready.

Tool version differences do not use the same changed classification. Ready is a local authorization observation, not a successful external call. Missing/foreign Session returns `404 session_not_found` for environment and authorization reads.

## Revoke a connection for this Session

`DELETE /v1/sessions/{id}/connections/{connection}` requires an owner and returns **200**, the updated authorization object, not 204. Only Tool or HTTP connections present in the pinned definition are eligible; another binding/kind returns `403 connection_not_bound`.

```sh theme={null}
curl --fail-with-body --silent --show-error --request DELETE \
  -H "Authorization: Bearer $HEXAGON_API_TOKEN" \
  "$HEXAGON_API_URL/v1/sessions/$HEXAGON_SESSION_ID/connections/$HEXAGON_CONNECTION_ID"
```

It inserts a durable Session-specific revocation and marks that Session/connection's access grants revoked. Repetition does not duplicate the revocation row. This is not deletion of the shared connection, Provider-side account revocation or a change to another Session. No reversal endpoint is defined here. The statements are not wrapped in one transaction; if a response fails, read authorization and grants, then repeat the same revocation if needed. A recorded revocation itself is checked during future proxy authorization. Already dispatched external operations cannot be recalled.

## List access-grant metadata

`GET /v1/sessions/{id}/access` returns **200**, `{grants:[...]}` ordered by creation time, without pagination. Each grant contains `id`, `session_id`, `connection_id`, nullable `run_id`, `expires_at`, `revoked_at`, `created_at`. Expired/revoked grants remain visible. No token or base\_url is returned by this list. Missing/foreign Session returns 404.

```sh theme={null}
curl --fail-with-body --silent --show-error \
  -H "Authorization: Bearer $HEXAGON_API_TOKEN" \
  "$HEXAGON_API_URL/v1/sessions/$HEXAGON_SESSION_ID/access"
```

## Issue scoped proxy access

`POST /v1/sessions/{id}/access` accepts strict `{connection_id:UUID}` and returns **201**, `{id,base_url,token,expires_at,implementation:"external_proxy"}` with `Cache-Control:no-store`. The generated base\_url is the configured credential ingress origin plus `/access/{grant-id}`. Token is a delegated credential, not the raw Provider secret.

Save a body with your actual connection UUID as `access-request.json`:

```json theme={null}
{"connection_id":"00000000-0000-4000-8000-000000000001"}
```

```sh theme={null}
umask 077
curl --fail-with-body --silent --show-error \
  -H "Authorization: Bearer $HEXAGON_API_TOKEN" -H 'Content-Type: application/json' \
  --data-binary @access-request.json --output session-access-grant.json \
  "$HEXAGON_API_URL/v1/sessions/$HEXAGON_SESSION_ID/access"
```

Replace the placeholder UUID. Store the response privately, check command success and never send an owner token to the proxy. Credential ingress must be configured as a valid HTTPS origin. The Session must be open; non-open Sessions are reported as `404 session_not_found` by this operation. Eligible connections are the Session's model connection or bound protected HTTP connections, not Tool bindings. A connection must be enabled, ready, undeleted and match its pinned version. Session revocation denies issuance.

Grant lifetime is `min(3600, Session timeout_seconds)` seconds from issuance, with 600 seconds as fallback; this endpoint has no user TTL or Run ID parameter. Public issuance leaves run\_id null. Internal worker issuance can attach a Run; during use, that Run must belong to the same Session and be `provisioning`, `running`, `waiting_authorization` or `waiting_approval`. A queued, cancelling or terminal Run does not satisfy that check. Each use rechecks expiry/revocation, open Session, connection version/readiness, managed Secret availability and applicable Run state. Thus issuance does not guarantee a later request will be authorized. Issuance checks the connection row and pinned version; the managed-Secret availability check is performed during proxy authorization. Do not use a newly issued token as proof that its upstream credential can currently be used.

There is no idempotency key. Repeating creates another grant; its plaintext cannot be recovered through the list. If the response is lost, inspect/revoke identified unused grants before intentionally issuing another. Revoking one grant differs from revoking the Session's entire connection binding.

| Issuance error | Status / interpretation |
| - | - |
| credential\_proxy\_not\_configured / credential\_proxy\_url\_invalid | 409; fix ingress configuration |
| session\_not\_found | 404; missing/foreign or not open |
| connection\_not\_bound | 403; not the model or bound HTTP connection |
| access\_denied | 403; Session connection revoked |
| connection\_not\_ready | 409; connection absent/unavailable/wrong kind |
| session\_connection\_changed | 409; current version differs from pinned |
| session\_access\_expired | 409; computed grant deadline invalid |

Malformed strict bodies return `400 invalid_request`. The subsequent proxy transport has separate policy and authentication handling; see [protected HTTP APIs](https://docs.hexagon.autos/en/integrations/http-tools.md).

## Revoke one grant

`DELETE /v1/access/{id}` returns **204** with no body. Repeated revocation of an existing grant succeeds and updates its revoked timestamp; unknown/foreign grant returns `404 access_not_found`.

```sh theme={null}
curl --fail-with-body --silent --show-error --request DELETE \
  -H "Authorization: Bearer $HEXAGON_API_TOKEN" \
  "$HEXAGON_API_URL/v1/access/$HEXAGON_GRANT_ID"
```

This does not close the Session, revoke its account credentials or undo previously dispatched requests. These access grants are distinct from [browser preview grants](https://docs.hexagon.autos/en/reference/artifacts-previews.md).

## SDK examples: inspect, issue and revoke separately

Initialize `client` using the SDK setup for a trusted backend; TypeScript helpers use the imported `Hexagon` type. All functions below are independent: defining them makes no request. Supply a saved Session ID and the relevant connection or grant ID, after checking your application's user-to-resource mapping. Use an owner client for the combined inspection helper because Session authorization is owner-only, even though grant listing also permits application tokens.

```python theme={null}
def inspect_session_access(client, session_id):
    authorization = client.session_authorization(session_id)
    grants = client.list_access(session_id)['grants']
    return {'authorization': authorization, 'grants': grants}


def read_private_process_environment(client, session_id):
    return client.session_environment(session_id)


def issue_private_access(client, session_id, connection_id):
    return client.create_access(session_id, connection_id)


def revoke_one_access_grant(client, grant_id):
    client.revoke_access(grant_id)  # HTTP 204 -> None


def revoke_session_binding(client, session_id, connection_id):
    updated = client.revoke_session_connection(session_id, connection_id)
    return updated  # JSON authorization object, not None
```

```typescript theme={null}
async function inspectSessionAccess(client: Hexagon, sessionId: string) {
  const authorization = await client.sessionAuthorization(sessionId);
  const { grants } = await client.listAccess(sessionId);
  return { authorization, grants };
}

async function readPrivateProcessEnvironment(client: Hexagon, sessionId: string) {
  return await client.sessionEnvironment(sessionId);
}

async function issuePrivateAccess(client: Hexagon, sessionId: string, connectionId: string) {
  return await client.createAccess(sessionId, connectionId);
}

async function revokeOneAccessGrant(client: Hexagon, grantId: string) {
  await client.revokeAccess(grantId); // HTTP 204 -> undefined
}

async function revokeSessionBinding(client: Hexagon, sessionId: string, connectionId: string) {
  const updated = await client.revokeSessionConnection(sessionId, connectionId);
  return updated; // JSON authorization object, not undefined
}
```

The inspection helper makes two separate reads, not an atomic snapshot. It never requests environment plaintext or an access token. Returned account names and resource IDs can still be private. Expired/revoked grants remain in the list; do not treat its length as the number of usable grants. A local `ready` authorization observation does not verify provider access.

Use the environment helper only when you deliberately need the immutable Agent-process values. It returns `{env, scope, mutable}` with plaintext `env`; keep it out of normal diagnostics, UI state and logs. For names only, use the redacted initialization endpoint. Environment inspection neither retrieves protected Provider credentials nor changes the running process.

The issue helper returns `{id, base_url, token, expires_at, implementation}`. Persist the grant ID and expiry privately and transfer the delegated token only to the intended authorized consumer. Use this token at the returned credential-proxy URL, never the owner/application control-plane token. Grant creation is for the Session's model or bound protected HTTP connection; it cannot issue a Tool-binding grant or accept custom TTL/Run parameters. Proxy method/path policy still applies, and an access grant does not create a Tool approval flow.

| Intended action | Which helper and result | What remains separate |
| - | - | - |
| Remove one leaked or unused delegated token | Revoke-one helper with grant ID; success has no JSON | Other grants and the Session's connection binding remain; this does not reverse an upstream write |
| Stop this Session using a bound Tool/HTTP connection | Revoke-binding helper with Session and connection IDs; inspect returned `connections` state | No reversal endpoint; other Sessions, shared credentials and cloud compute remain independent |
| Recover a lost issuance response | Inspect metadata, identify and revoke unused grants, then deliberately issue again if needed | Token plaintext is not recoverable from listing; issuance has no deduplication key |
| Recover an interrupted binding revocation | Read authorization and grant metadata; repeat the same revocation if required | Its statements are not one transaction; do not assume every grant update completed from one failed response |

These helpers propagate errors without retries. Treat `session_connection_changed` as a pinned-version mismatch to investigate, not permission to modify an existing Session's bindings. `connection_not_bound` means the requested kind/binding is not eligible; `access_denied` can reflect Session revocation. A 404 on grant issuance can also mean the Session is no longer open. Check the operation-specific error table above before acting. Use the [protected HTTP guide](https://docs.hexagon.autos/en/integrations/http-tools.md) for proxy requests and [Tool authorization](https://docs.hexagon.autos/en/build/tool-authorization.md) for broker-managed calls.

Local syntax/type checks do not verify a live environment read, proxy request or revocation. The example definitions themselves do not retrieve any secret or issue credentials.

Sources: [Session configuration](https://github.com/NexusFox88/docs/blob/main/resources/modules/execution/session-configuration.ts), [access issuance and authorization](https://github.com/NexusFox88/docs/blob/main/resources/modules/access/access.ts), [HTTP routes](https://github.com/NexusFox88/docs/blob/main/resources/apps/control-plane/server.ts). This page is source-reviewed; no environment values were retrieved and no grants were issued/revoked in this documentation pass.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.