Skip to main content

​
Overview

The Vault service 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.

​
Store

Store an encrypted credential in the vault. Upserts on PrincipalID + Service. 
result, err := client.Vault.Store(ctx, grantex.StoreCredentialParams{
    PrincipalID:    "user_abc123",
    Service:        "github",
    AccessToken:    "gho_xxxxxxxxxxxx",
    CredentialType: "oauth2",
    RefreshToken:   "ghr_xxxxxxxxxxxx",
    TokenExpiresAt: "2026-04-10T00:00:00Z",
    Metadata:       map[string]interface{}{"scope": "repo,user"},
})
if err != nil {
    log.Fatal(err)
}
fmt.Printf("Credential ID: %s\n", result.ID)
fmt.Printf("Service: %s\n", result.Service)

​
Parameters

ParameterTypeRequiredDescription
PrincipalIDstringYesThe end-user who owns this credential.
ServicestringYesService name (e.g., "github", "slack").
AccessTokenstringYesThe upstream access token (encrypted at rest).
CredentialTypestringNoCredential type (e.g., "oauth2", "api_key").
RefreshTokenstringNoOptional refresh token.
TokenExpiresAtstringNoISO 8601 expiry for the upstream token.
Metadatamap[string]interface{}NoArbitrary metadata to store alongside the credential.

​
Response (StoreCredentialResponse)

FieldTypeDescription
IDstringUnique credential identifier.
PrincipalIDstringThe principal who owns the credential.
ServicestringService name.
CredentialTypestringCredential type.
CreatedAtstringISO 8601 timestamp when stored.

​
List

List credential metadata. Raw tokens are never returned by this endpoint. 
creds, err := client.Vault.List(ctx, &grantex.ListVaultCredentialsParams{
    PrincipalID: "user_abc123",
    Service:     "github",
})
if err != nil {
    log.Fatal(err)
}
for _, cred := range creds {
    fmt.Printf("%s (%s) - expires %v\n", cred.Service, cred.CredentialType, cred.TokenExpiresAt)
}

​
Parameters

ParameterTypeRequiredDescription
PrincipalIDstringNoFilter by principal ID.
ServicestringNoFilter by service name.

​
Response

Returns []VaultCredential. See Get below for the VaultCredential struct fields.

​
Get

Get credential metadata by ID. Does not return the raw token. 
cred, err := client.Vault.Get(ctx, "cred_01HXYZ...")
if err != nil {
    log.Fatal(err)
}
fmt.Printf("Service: %s\n", cred.Service)
fmt.Printf("Type: %s\n", cred.CredentialType)

​
Parameters

ParameterTypeRequiredDescription
credentialIDstringYesThe credential ID to retrieve.

​
VaultCredential

FieldTypeDescription
IDstringUnique credential identifier.
PrincipalIDstringThe principal who owns the credential.
ServicestringService name.
CredentialTypestringCredential type.
TokenExpiresAt*stringISO 8601 expiry for the upstream token.
Metadatamap[string]interface{}Stored metadata.
CreatedAtstringISO 8601 creation timestamp.
UpdatedAtstringISO 8601 last-updated timestamp.

​
Delete

Delete a credential from the vault. 
err := client.Vault.Delete(ctx, "cred_01HXYZ...")
if err != nil {
    log.Fatal(err)
}

​
Parameters

ParameterTypeRequiredDescription
credentialIDstringYesThe credential ID to delete.

​
Exchange

Exchange a Grantex grant token for an upstream service credential. Unlike other methods, this uses the grant token (not the API key) as the Bearer token, allowing agents to retrieve stored credentials at runtime. 
result, err := client.Vault.Exchange(ctx, "eyJhbGciOiJSUzI1NiIs...", grantex.ExchangeCredentialParams{
    Service: "github",
})
if err != nil {
    log.Fatal(err)
}
fmt.Printf("Access token: %s\n", result.AccessToken)
fmt.Printf("Service: %s\n", result.Service)

​
Parameters

ParameterTypeRequiredDescription
grantTokenstringYesA valid Grantex grant token (JWT).
ServicestringYesThe service to retrieve credentials for.

​
Response (ExchangeCredentialResponse)

FieldTypeDescription
AccessTokenstringThe upstream access token.
ServicestringService name.
CredentialTypestringCredential type.
TokenExpiresAt*stringISO 8601 expiry for the token.
Metadatamap[string]interface{}Stored metadata.