Credential Endpoints

Credentials are the authentication tokens associated with identities. VeraID supports standard long-lived credentials, just-in-time (JIT) temporary credentials, and scoped access tokens with usage limits.

List Credentials

Retrieve a paginated list of credentials with optional filters and summary statistics.

GET /api/v1/credentials

Query Parameters

Parameter	Type	Description
status	string	Filter by status: ACTIVE, EXPIRED, REVOKED, SUSPENDED
expiring	boolean	If true, return only credentials expiring within 30 days
limit	number	Items per page (default: 20, max: 100)
offset	number	Number of items to skip (for offset-based pagination)

Example Request

curl -X GET "https://app.veraid.io/api/v1/credentials?status=ACTIVE&expiring=true&limit=25" \
  -H "Authorization: Bearer kd_live_abc123..."

Example Response

{
  "data": [
    {
      "id": "cred_abc123",
      "name": "Production API Key",
      "identityId": "id_xyz789",
      "identityName": "aws-deploy-prod",
      "type": "API_KEY",
      "status": "ACTIVE",
      "scopes": ["secrets.read", "identities.read"],
      "isTemporary": false,
      "usageCount": 1847,
      "maxUsageCount": null,
      "lastUsedAt": "2026-03-19T09:15:00Z",
      "expiresAt": "2026-04-15T00:00:00Z",
      "createdAt": "2026-01-15T10:00:00Z"
    }
  ],
  "stats": {
    "byStatus": {
      "ACTIVE": 142,
      "EXPIRED": 23,
      "REVOKED": 8,
      "SUSPENDED": 3
    },
    "expiringSoon": 12
  },
  "pagination": {
    "limit": 25,
    "offset": 0,
    "total": 12,
    "hasMore": false
  }
}

---

Create Credential

Create a new credential for an identity. The credential secret is returned only in the creation response and cannot be retrieved again.

POST /api/v1/credentials

Request Body

Field	Type	Required	Description
identityId	string	Yes	The identity this credential belongs to
name	string	Yes	Display name for the credential (2-100 characters)
type	string	No	Credential type (default: API_KEY)
scopes	string[]	No	Permission scopes for this credential
isTemporary	boolean	No	Whether this is a temporary credential (default: false)
ttl	number	No	Time-to-live in seconds (for temporary credentials)
maxUsageCount	number	No	Maximum number of times the credential can be used
expiresAt	string	No	ISO 8601 expiration date

Example Request

curl -X POST https://app.veraid.io/api/v1/credentials \
  -H "Authorization: Bearer kd_live_abc123..." \
  -H "Content-Type: application/json" \
  -d '{
    "identityId": "id_xyz789",
    "name": "Production API Key",
    "scopes": ["secrets.read", "identities.read"],
    "expiresAt": "2026-06-19T00:00:00Z"
  }'

Example Response

{
  "id": "cred_new123",
  "name": "Production API Key",
  "identityId": "id_xyz789",
  "type": "API_KEY",
  "status": "ACTIVE",
  "scopes": ["secrets.read", "identities.read"],
  "isTemporary": false,
  "credential": "kd_live_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6",
  "usageCount": 0,
  "maxUsageCount": null,
  "lastUsedAt": null,
  "expiresAt": "2026-06-19T00:00:00Z",
  "createdAt": "2026-03-19T10:00:00Z"
}

Danger

The credential field is only returned in the creation response. Store it securely immediately. If lost, you must rotate the credential to generate a new one. VeraID stores only a cryptographic hash of the credential and cannot recover the original value.

---

Create JIT Credential

Create a just-in-time temporary credential that automatically expires after the specified duration.

POST /api/v1/credentials/jit

Request Body

Field	Type	Required	Description
identityId	string	Yes	The identity this JIT credential belongs to
name	string	No	Display name (auto-generated if not provided)
scopes	string[]	No	Permission scopes for this credential
duration	string	Yes	Duration in the format \d+[smhd] (e.g., 30m, 4h, 1d)
maxUsage	number	No	Maximum number of times the credential can be used

Duration Format

Suffix	Meaning	Example
s	Seconds	300s = 5 minutes
m	Minutes	30m = 30 minutes
h	Hours	4h = 4 hours
d	Days	1d = 24 hours

Example Request

curl -X POST https://app.veraid.io/api/v1/credentials/jit \
  -H "Authorization: Bearer kd_live_abc123..." \
  -H "Content-Type: application/json" \
  -d '{
    "identityId": "id_xyz789",
    "name": "Deploy Token - Release v2.5",
    "scopes": ["deploy.execute", "secrets.read"],
    "duration": "2h",
    "maxUsage": 5
  }'

Example Response

{
  "id": "cred_jit456",
  "name": "Deploy Token - Release v2.5",
  "identityId": "id_xyz789",
  "type": "JIT",
  "status": "ACTIVE",
  "scopes": ["deploy.execute", "secrets.read"],
  "isTemporary": true,
  "credential": "kd_jit_x1y2z3a4b5c6d7e8f9g0h1i2j3k4l5m6",
  "usageCount": 0,
  "maxUsage": 5,
  "lastUsedAt": null,
  "expiresAt": "2026-03-19T12:00:00Z",
  "createdAt": "2026-03-19T10:00:00Z"
}

Tip

JIT credentials are ideal for deployment pipelines, maintenance windows, and ad-hoc debugging sessions. They eliminate the risk of long-lived credentials being forgotten or misused.

---

Verify Credential

Verify whether a credential is valid and retrieve the associated identity information. This endpoint is typically used by services to validate incoming API keys.

POST /api/v1/credentials/verify

Request Body

Field	Type	Required	Description
credential	string	Yes	The full credential string (e.g., kd_live_abc123...)

Example Request

curl -X POST https://app.veraid.io/api/v1/credentials/verify \
  -H "Authorization: Bearer kd_live_abc123..." \
  -H "Content-Type: application/json" \
  -d '{
    "credential": "kd_live_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6"
  }'

Example Response (Valid)

{
  "valid": true,
  "identity": {
    "id": "id_xyz789",
    "name": "aws-deploy-prod",
    "type": "SERVICE_ACCOUNT",
    "status": "ACTIVE",
    "riskScore": 42,
    "tags": ["production", "aws"]
  },
  "credential": {
    "id": "cred_abc123",
    "name": "Production API Key",
    "scopes": ["secrets.read", "identities.read"],
    "isTemporary": false,
    "usageCount": 1848,
    "expiresAt": "2026-06-19T00:00:00Z"
  }
}

Example Response (Invalid)

{
  "valid": false,
  "identity": null,
  "credential": null
}

Note

The verify endpoint increments the credential’s usage counter. If the credential has a maxUsageCount, verification counts toward that limit.

---

Rotate Credential

Rotate an existing credential, generating a new secret and optionally maintaining the old credential for a grace period.

POST /api/v1/credentials/{id}/rotate

Request Body

Field	Type	Required	Description
gracePeriod	number	No	Seconds to keep the old credential active alongside the new one (default: 0, meaning immediate revocation)

Example Request

curl -X POST https://app.veraid.io/api/v1/credentials/cred_abc123/rotate \
  -H "Authorization: Bearer kd_live_abc123..." \
  -H "Content-Type: application/json" \
  -d '{
    "gracePeriod": 86400
  }'

Example Response

{
  "id": "cred_abc123",
  "name": "Production API Key",
  "identityId": "id_xyz789",
  "type": "API_KEY",
  "status": "ACTIVE",
  "scopes": ["secrets.read", "identities.read"],
  "credential": "kd_live_n7o8p9q0r1s2t3u4v5w6x7y8z9a0b1c2",
  "previousCredential": {
    "status": "GRACE_PERIOD",
    "expiresAt": "2026-03-20T10:00:00Z"
  },
  "usageCount": 0,
  "lastUsedAt": null,
  "expiresAt": "2026-06-19T00:00:00Z",
  "rotatedAt": "2026-03-19T10:00:00Z"
}

Caution

When using a grace period, both the old and new credentials are valid simultaneously. Update your services to use the new credential before the grace period expires. The old credential is automatically revoked when the grace period ends.