Authentication

This section explains how to authenticate with the Concord eVault API using Access Keys.

Overview

Concord eVault uses Access Keys to authenticate API requests from integration partners and automated systems. Access Keys provide secure, scoped access to specific API endpoints without requiring user credentials.

What are Access Keys?

Access Keys are long-lived API credentials that allow external systems to interact with Concord eVault programmatically. Each key is associated with a specific vault and has a defined set of permissions (scopes) that control what operations it can perform.

When to use Access Keys

Key features

Access Keys are vault-scoped (each Access Key is tied to a specific vault), have granular permissions (keys are assigned specific scopes that control which endpoints they can access), are auditable (all API activity is logged and associated with the Access Key used), are revocable (keys can be revoked at any time without affecting other integrations), and are rate-limited (keys are subject to rate limits to ensure fair usage).

Access Key format

Access Keys follow this format:

vv_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

The prefix is vv_live_ (8 characters), the secret is 32 alphanumeric characters, and the total length is 40 characters. Example:

vv_live_a2B9c3D8e7F6g5H4i3J2k1L0m9N8o7P6

Creating an Access Key

Access Keys are created through the Concord eVault portal by Organization Administrators.

1. Log into the Concord eVault portal.
2. Navigate to Organization › Access Keys.
3. Click Create Access Key.
4. Configure the key:
   • Name — a descriptive name for the key (e.g., “Production Integration”).
   • Vault — select the vault this key will access.
   • Expiration — choose how long the key should remain valid: 7 days, 30 days, 90 days, or Never. See Expiration below for guidance.
   • Scopes — select the permissions this key should have.
5. Click Create.
6. Important: copy the full key immediately. It will only be shown once.

Expiration

Access Keys can be configured with an expiration at the time of creation:

The maximum fixed expiration is 90 days. For longer-lived integrations, choose Never and revoke the key manually when it is no longer needed. An expired key returns 401 Unauthorized on authentication. The expiration cannot be changed after creation — to change it, create a new key with the new expiration and revoke the old one. Keys with a fixed expiration trigger email notifications to organization administrators at 30, 7, and 1 day(s) before expiry. Keys set to Never do not send notifications — rotation is your responsibility.

Using Access Keys

Include your Access Key in the Authorization header of every API request:

Authorization: Bearer vv_live_your_access_key_here

Available scopes

Access Keys can be granted one or more scopes. Scopes follow a hierarchical pattern where a parent scope grants all child permissions.

Scope recommendations

Best practice: Always request the minimum scopes required for your integration. You can create multiple Access Keys with different scopes for different purposes within the same integration.

Rate limiting

Access Key requests are subject to rate limiting to ensure fair usage and protect the system from abuse.

Rate limits are applied per Access Key. If you need higher throughput, consider distributing requests across multiple Access Keys (if your use case permits) or contact support.

When rate limited, the response includes a Retry-After header:

HTTP/1.1 429 Too Many Requests
Retry-After: 60
Content-Type: application/json

The rate limit response body:

{
  "title": "Too Many Requests",
  "status": 429,
  "detail": "Rate limit exceeded for this access key. Please retry after the specified time.",
  "retryAfterSeconds": 60
}

When you receive a 429 response, wait for the duration specified in the Retry-After header before retrying. Implement exponential backoff in your integration to handle rate limits gracefully.

Error responses

401 Unauthorized

Returned when the Access Key is missing, invalid, or expired.

{
  "type": "https://tools.ietf.org/html/rfc7235#section-3.1",
  "title": "Unauthorized",
  "status": 401
}

Common causes: missing Authorization header, invalid key format, key has been revoked, or key has expired.

403 Forbidden

Returned when the Access Key is valid but lacks the required scope.

{
  "type": "https://tools.ietf.org/html/rfc7231#section-6.5.3",
  "title": "Forbidden",
  "status": 403
}

Solution: Request an Access Key with the appropriate scope from your Organization Administrator.

Security best practices

1. Never share Access Keys in public repositories, client-side code, or logs.
2. Use environment variables to store keys in your application.
3. Rotate keys regularly — create new keys and revoke old ones periodically. Keys configured to Never expire must be rotated proactively on a schedule your team tracks, since the system will not send reminder emails.
4. Use minimum required scopes — only request the permissions you need.
5. Monitor key usage through the Concord eVault activity logs.

Storing keys securely: Store your Access Key in environment variables or a secure secrets manager. Never hardcode keys in source code or commit them to version control.

Key management

Viewing keys

Organization Administrators can view all Access Keys in the portal, including key name and creation date, assigned scopes, and last used timestamp. Note: The full key value is never displayed after creation for security reasons. Only the first 16 and last 4 characters are shown.

Revoking keys

To revoke an Access Key, navigate to Organization › Access Keys, find the key to revoke, click Revoke, and confirm the action. Revoking a key immediately invalidates it; any integrations using this key will stop working.

Rotating keys

To rotate keys safely, create a new Access Key with the same scopes, update your integration to use the new key, verify the integration works with the new key, and revoke the old key.

Next: Packages API.