Skip to main content

​
Endpoint

POST /v1/vault/credentials

​
Authentication

Requires a developer API key in the Authorization header.

​
Request Headers

HeaderValue
AuthorizationBearer <api_key>
Content-Typeapplication/json

​
Request Body

FieldTypeRequiredDescription
principalIdstringYesThe principal (end-user) who owns this credential
servicestringYesService identifier (e.g. "github", "slack", "google")
accessTokenstringYesThe access token to store (encrypted at rest)
credentialTypestringNoCredential type (default "oauth2")
refreshTokenstringNoOptional refresh token (encrypted at rest)
tokenExpiresAtstringNoISO-8601 expiry timestamp for the access token
metadataobjectNoArbitrary metadata (e.g. scopes, account info)

​
Example Request

curl -X POST https://grantex-auth-dd4mtrt2gq-uc.a.run.app/v1/vault/credentials \
  -H "Authorization: Bearer gx_..." \
  -H "Content-Type: application/json" \
  -d '{
    "principalId": "user_abc123",
    "service": "github",
    "accessToken": "ghp_xxxxxxxxxxxx",
    "refreshToken": "ghr_xxxxxxxxxxxx",
    "tokenExpiresAt": "2026-04-06T12:00:00.000Z",
    "metadata": { "scopes": ["repo", "read:org"] }
  }'

​
Response — 201 Created

{
  "id": "vc_01HXYZ...",
  "principalId": "user_abc123",
  "service": "github",
  "credentialType": "oauth2",
  "createdAt": "2026-04-05T12:00:00.000Z"
}

​
Response Fields

FieldTypeDescription
idstringUnique vault credential ID
principalIdstringThe principal who owns this credential
servicestringService identifier
credentialTypestringCredential type
createdAtstringISO-8601 creation timestamp
If a credential already exists for the same (developerId, principalId, service) combination, it will be updated (upsert behavior). The raw access token and refresh token are never returned in any response — they are stored encrypted and only retrievable via the Exchange endpoint.

​
Error Responses

StatusCodeDescription
400BAD_REQUESTMissing principalId, service, or accessToken
401UNAUTHORIZEDInvalid or missing API key

​
SDK Examples

import Grantex from '@grantex/sdk';

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

const cred = await grantex.vault.store({
  principalId: 'user_abc123',
  service: 'github',
  accessToken: 'ghp_xxxxxxxxxxxx',
  refreshToken: 'ghr_xxxxxxxxxxxx',
  metadata: { scopes: ['repo', 'read:org'] },
});