Skip to main content

​
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

ParameterTypeRequiredDescription
principal_idstrYesThe end-user who owns this credential.
servicestrYesService name (e.g., "github", "slack").
access_tokenstrYesThe upstream access token to store (encrypted at rest).
credential_typestr | NoneNoCredential type (e.g., "oauth2", "api_key").
refresh_tokenstr | NoneNoOptional refresh token.
token_expires_atstr | NoneNoISO 8601 expiry for the upstream token.
metadatadict[str, Any] | NoneNoArbitrary metadata to store alongside the credential.

​
StoreCredentialResponse

FieldTypeDescription
idstrUnique credential identifier.
principal_idstrThe principal who owns the credential.
servicestrService name.
credential_typestrCredential type.
created_atstrISO 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

ParameterTypeRequiredDescription
principal_idstr | NoneNoFilter by principal ID.
servicestr | NoneNoFilter by service name.

​
ListVaultCredentialsResponse

FieldTypeDescription
credentialstuple[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

ParameterTypeRequiredDescription
credential_idstrYesThe credential ID to retrieve.

​
VaultCredential

FieldTypeDescription
idstrUnique credential identifier.
principal_idstrThe principal who owns the credential.
servicestrService name.
credential_typestrCredential type.
token_expires_atstr | NoneISO 8601 expiry for the upstream token.
metadatadict[str, Any]Stored metadata.
created_atstrISO 8601 creation timestamp.
updated_atstrISO 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

ParameterTypeRequiredDescription
credential_idstrYesThe 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

ParameterTypeRequiredDescription
grant_tokenstrYesA valid Grantex grant token (JWT).
servicestrYesThe service to retrieve credentials for.

​
ExchangeCredentialResponse

FieldTypeDescription
access_tokenstrThe upstream access token.
servicestrService name.
credential_typestrCredential type.
token_expires_atstr | NoneISO 8601 expiry for the token.
metadatadict[str, Any]Stored metadata.