Documentation Index
Fetch the complete documentation index at: https://docs.grantex.dev/llms.txt
Use this file to discover all available pages before exploring further.
Overview
The vault client manages encrypted service credentials. Store upstream credentials (e.g., OAuth tokens for third-party APIs), retrieve metadata, delete credentials, and exchange Grantex grant tokens for stored service tokens at runtime.
Access the vault client via client.vault.
Store
Store an encrypted credential in the vault. Upserts on the principal_id + service combination.
from grantex import Grantex, StoreCredentialParams
with Grantex(api_key="gx_live_...") as client:
result = client.vault.store(StoreCredentialParams(
principal_id="user_abc123",
service="github",
access_token="gho_xxxxxxxxxxxx",
credential_type="oauth2",
refresh_token="ghr_xxxxxxxxxxxx",
token_expires_at="2026-04-10T00:00:00Z",
metadata={"scope": "repo,user"},
))
print(f"Credential ID: {result.id}")
print(f"Service: {result.service}")
print(f"Created: {result.created_at}")
StoreCredentialParams
| Parameter | Type | Required | Description |
|---|
principal_id | str | Yes | The end-user who owns this credential. |
service | str | Yes | Service name (e.g., "github", "slack"). |
access_token | str | Yes | The upstream access token to store (encrypted at rest). |
credential_type | str | None | No | Credential type (e.g., "oauth2", "api_key"). |
refresh_token | str | None | No | Optional refresh token. |
token_expires_at | str | None | No | ISO 8601 expiry for the upstream token. |
metadata | dict[str, Any] | None | No | Arbitrary metadata to store alongside the credential. |
StoreCredentialResponse
| Field | Type | Description |
|---|
id | str | Unique credential identifier. |
principal_id | str | The principal who owns the credential. |
service | str | Service name. |
credential_type | str | Credential type. |
created_at | str | ISO 8601 timestamp when stored. |
List
List credential metadata. Raw tokens are never returned by this endpoint.
from grantex import Grantex, ListVaultCredentialsParams
with Grantex(api_key="gx_live_...") as client:
result = client.vault.list(ListVaultCredentialsParams(
principal_id="user_abc123",
service="github",
))
for cred in result.credentials:
print(f"{cred.service} ({cred.credential_type}) - expires {cred.token_expires_at}")
ListVaultCredentialsParams
| Parameter | Type | Required | Description |
|---|
principal_id | str | None | No | Filter by principal ID. |
service | str | None | No | Filter by service name. |
ListVaultCredentialsResponse
| Field | Type | Description |
|---|
credentials | tuple[VaultCredential, ...] | Credential metadata records. |
Get
Get credential metadata by ID. Does not return the raw token.
from grantex import Grantex
with Grantex(api_key="gx_live_...") as client:
cred = client.vault.get("cred_01HXYZ...")
print(f"Service: {cred.service}")
print(f"Type: {cred.credential_type}")
print(f"Expires: {cred.token_expires_at}")
Parameters
| Parameter | Type | Required | Description |
|---|
credential_id | str | Yes | The credential ID to retrieve. |
VaultCredential
| Field | Type | Description |
|---|
id | str | Unique credential identifier. |
principal_id | str | The principal who owns the credential. |
service | str | Service name. |
credential_type | str | Credential type. |
token_expires_at | str | None | ISO 8601 expiry for the upstream token. |
metadata | dict[str, Any] | Stored metadata. |
created_at | str | ISO 8601 creation timestamp. |
updated_at | str | ISO 8601 last-updated timestamp. |
Delete
Delete a credential from the vault.
from grantex import Grantex
with Grantex(api_key="gx_live_...") as client:
client.vault.delete("cred_01HXYZ...")
Parameters
| Parameter | Type | Required | Description |
|---|
credential_id | str | Yes | The credential ID to delete. |
Exchange
Exchange a Grantex grant token for an upstream service credential. This endpoint uses the grant token (not the API key) as the Bearer token, allowing agents to retrieve stored credentials at runtime without exposing the developer’s API key.
from grantex import Grantex, ExchangeCredentialParams
with Grantex(api_key="gx_live_...") as client:
result = client.vault.exchange(
grant_token="eyJhbGciOiJSUzI1NiIs...",
params=ExchangeCredentialParams(service="github"),
)
print(f"Access token: {result.access_token}")
print(f"Service: {result.service}")
print(f"Expires: {result.token_expires_at}")
Parameters
| Parameter | Type | Required | Description |
|---|
grant_token | str | Yes | A valid Grantex grant token (JWT). |
service | str | Yes | The service to retrieve credentials for. |
ExchangeCredentialResponse
| Field | Type | Description |
|---|
access_token | str | The upstream access token. |
service | str | Service name. |
credential_type | str | Credential type. |
token_expires_at | str | None | ISO 8601 expiry for the token. |
metadata | dict[str, Any] | Stored metadata. |
