List Vault Credentials

List vault credential metadata for the authenticated developer. Does not return raw tokens.

Endpoint

GET /v1/vault/credentials

Authentication

Requires a developer API key in the Authorization header.

Request Headers

Header	Value
Authorization	Bearer <api_key>

Query Parameters

Parameter	Type	Required	Description
principalId	string	No	Filter by principal ID
service	string	No	Filter by service name

Example Request

curl "https://api.grantex.dev/v1/vault/credentials?principalId=user_abc123" \
  -H "Authorization: Bearer gx_..."

Response — 200 OK

{
  "credentials": [
    {
      "id": "vc_01HXYZ...",
      "principalId": "user_abc123",
      "service": "github",
      "credentialType": "oauth2",
      "tokenExpiresAt": "2026-04-06T12:00:00.000Z",
      "metadata": { "scopes": ["repo", "read:org"] },
      "createdAt": "2026-04-05T12:00:00.000Z",
      "updatedAt": "2026-04-05T12:00:00.000Z"
    }
  ]
}

Response Fields

Field	Type	Description
credentials	array	Array of credential metadata objects
credentials[].id	string	Unique vault credential ID
credentials[].principalId	string	The principal who owns this credential
credentials[].service	string	Service identifier
credentials[].credentialType	string	Credential type (e.g. "oauth2")
credentials[].tokenExpiresAt	string | null	ISO-8601 token expiry, or null if not set
credentials[].metadata	object	Arbitrary metadata
credentials[].createdAt	string	ISO-8601 creation timestamp
credentials[].updatedAt	string	ISO-8601 last update timestamp

Raw access tokens and refresh tokens are never included in list responses. Use the Exchange endpoint to retrieve a decrypted access token with a valid grant token.

Error Responses

Status	Code	Description
401	UNAUTHORIZED	Invalid or missing API key

SDK Examples

TypeScript

import Grantex from '@grantex/sdk';

const grantex = new Grantex({ apiKey: 'gx_...' });

const { credentials } = await grantex.vault.list({ principalId: 'user_abc123' });
for (const c of credentials) {
  console.log(`${c.service} — expires: ${c.tokenExpiresAt}`);
}

from grantex import Grantex

grantex = Grantex(api_key="gx_...")

result = grantex.vault.list(principal_id="user_abc123")
for c in result.credentials:
    print(f"{c.service} — expires: {c.token_expires_at}")