GDE Vault

API reference

Integrating with GDE Vault

Everything a service needs to submit, test, approve, and lease credentials through the vault's REST API. All request/response bodies are JSON.

Auth model

Four distinct credential classes, each authenticating a different kind of caller. One can never be used in place of another.

Developer session token

Signup/login, teams, application register/list/revoke/rotate

Authorization: Bearer <session_token> — issued at signup/login, revocable, DB-backed.

Application client secret

Every credential-lifecycle call (submit, metadata, test, approve, revoke, audit)

Authorization: Bearer <client_secret> + X-Vault-Actor-Id: <human actor id>. Looked up by hash against the application registry — never a shared static token.

Submission upload token

The one PUT .../payload call

Authorization: Bearer <upload_token> — single-use, short-lived, returned once at submission-creation time.

Workload lease token

POST /vault/v1/leases — the only endpoint that returns plaintext

Authorization: Bearer <token> — HMAC-signed, scoped to one exact (tenant, provider connection, environment, credential type), minted via /vault/v1/workload-tokens.

Getting started

Sign up, create a team, and register an application to get a client secret — the only credential your service needs going forward.

# 1. Create a developer account (returns a session_token)
curl -sX POST $VAULT_API/vault/v1/developers/signup \
  -H 'Content-Type: application/json' \
  -d '{"email":"you@example.com","password":"at least 8 characters"}'

# 2. Create a team
curl -sX POST $VAULT_API/vault/v1/teams \
  -H "Authorization: Bearer $SESSION_TOKEN" \
  -d '{"name":"Acme Inc"}'

# 3. Register an application for that team (returns client_secret, shown once)
curl -sX POST $VAULT_API/vault/v1/teams/$TEAM_ID/applications \
  -H "Authorization: Bearer $SESSION_TOKEN" \
  -d '{"name":"my-service"}'

# 4. Use the client_secret for every credential-lifecycle call from here on
curl -sX POST $VAULT_API/vault/v1/secret-submissions \
  -H "Authorization: Bearer $CLIENT_SECRET" \
  -H "X-Vault-Actor-Id: you@example.com" \
  -d '{
    "tenant_id": "11111111-1111-1111-1111-111111111111",
    "provider_connection_id": "pc_01",
    "environment": "sandbox",
    "credential_type": "OVA_API_CREDENTIAL",
    "metadata": {}
  }'
# -> { "submission_id", "upload_token", "vault_upload_url", "expires_at" }

# 5. Hand vault_upload_url + upload_token to whoever holds the secret — this PUT
#    goes straight to the vault, never through your own backend.
curl -sX PUT "$VAULT_UPLOAD_URL" \
  -H "Authorization: Bearer $UPLOAD_TOKEN" \
  -d '{"client_id":"...","client_secret":"..."}'

Endpoints

Identity & teams

POST/vault/v1/developers/signup

Create a developer account. Returns a session token.

none
POST/vault/v1/developers/login

Authenticate with email + password. Returns a session token.

none
POST/vault/v1/developers/logout

Revoke the current session.

developer session
GET/vault/v1/developers/me

Confirm a session token is still valid and get the developer it belongs to.

developer session
POST/vault/v1/teams

Create a team. The creator is granted the owner role.

developer session
GET/vault/v1/teams

List the teams the signed-in developer belongs to.

developer session
GET/vault/v1/teams/{team_id}

Get a team and its member list. Requires membership.

developer session
POST/vault/v1/teams/{team_id}/members

Add an existing developer (looked up by email) to the team.

developer session (owner)

Applications

POST/vault/v1/teams/{team_id}/applications

Register an application for the team. Returns a client secret, shown exactly once.

developer session (member)
GET/vault/v1/teams/{team_id}/applications

List the team's applications. Secrets are never returned again.

developer session (member)
POST/vault/v1/applications/{id}/revoke

Revoke an application. Idempotent.

developer session (member)
POST/vault/v1/applications/{id}/rotate

Replace an application's client secret atomically. No overlap window.

developer session (member)

Credential lifecycle

POST/vault/v1/secret-submissions

Mint a single-use upload token for one (tenant, provider connection, environment, credential type).

application secret
PUT/vault/v1/secret-submissions/{submission_id}/payload

Send the raw secret fields directly from the browser — never proxied through your own backend.

upload token
GET/vault/v1/credentials/{credential_ref}

Masked metadata for the current version. Never a secret field.

application secret
POST/vault/v1/credentials/{credential_ref}/test

Run the registered connectivity test against the pending version.

application secret
POST/vault/v1/credentials/{credential_ref}/approve

Approve and activate. Requires a checker distinct from the maker in production.

application secret
POST/vault/v1/credentials/{credential_ref}/revoke

Revoke a credential. Idempotent.

application secret

Rotation policy

GET/vault/v1/teams/{team_id}/rotation-policy

Get the team's rotation policy, or the built-in default if none is set.

developer session (member)
PUT/vault/v1/teams/{team_id}/rotation-policy

Set the team's rotation interval and reminder thresholds (days before expiry).

developer session (member)
GET/vault/v1/teams/{team_id}/rotation-reminders

Credentials submitted through this team's applications that are within a reminder threshold of secret_expires_at.

developer session (member)

Workloads & audit

POST/vault/v1/workload-tokens

Mint a lease token scoped to one credential's exact coordinates.

application secret
POST/vault/v1/leases

The only endpoint that returns plaintext. Scoped, audited, denies expired credentials.

workload token
GET/vault/v1/audit

List recent audit entries, optionally filtered by credential_ref/tenant_id.

application secret

Limitations

  • • Developer identity is password + session token only — WebAuthn/passkeys, OAuth/social login, and TOTP authenticator-app MFA are not yet available.
  • • Application names are globally unique, not per-team unique — pick a distinctive name when registering.
  • • Team and membership changes are not yet written to the audit log — only application and credential actions are.
  • • The generic connectivity tester only checks that the decrypted payload is a non-empty object — it has no provider-specific knowledge.
  • • Rotation reminders are surfaced via the API/console only — there is no email or Slack delivery. Poll rotation-reminders from your own scheduler if you need push notifications.

Already signed up? Sign in to manage your teams and applications in the console.