API v2 - Conventions and shared behaviors

This document describes the standard behaviors, rules, and formats that apply to all A2A API v2 endpoints. Read this before integrating with any v2 endpoint.

Response headers

Every v2 API response includes the following headers regardless of the endpoint or HTTP status code.

Note: When the rate limit is exceeded, the API returns 429 Too Many Requests. Wait until X-RateLimit-Reset before retrying.

Conditional requests

If-None-Match — conditional reads (GET)

Use the ETag value from a previous response as the If-None-Match header in a subsequent GET request. If the resource hasn't changed, the server returns 304 Not Modified with no body, saving bandwidth.

GET /api/v2/pam/credentials/101
If-None-Match: "abc123etag"

If-Match — conditional writes (PUT, PATCH, DELETE)

Use the ETag value from a previous read as the If-Match header in a write request. This prevents overwriting changes made by another process since your last read (optimistic concurrency control).

PUT /api/v2/pam/credentials/101
If-Match: "abc123etag"

Error format

All v2 error responses use a consistent JSON structure regardless of the endpoint.

{
    "error": {
        "code": "api.fields.invalid",
        "message": "One or more requested fields do not exist in the canonical model.",
        "details": [
            {
                "field": "credential.nonexistent",
                "reason": "Field not found in CredentialV2 schema."
            }
        ]
    }
}

403 vs 404 policy

The v2 API deliberately distinguishes between authorization failures and missing resources.

Note: Segura® never returns 404 to mask a 403. If you receive 404, the resource does not exist. If you receive 403, the resource exists but is outside the scope of your authorization.

Pagination

All list endpoints support two pagination strategies. Each endpoint documents which strategies it supports.

Offset pagination

Use for standard browsing and moderate dataset sizes.

Response fields:

Cursor-based pagination

Recommended for datasets exceeding 100,000 records. More efficient than offset pagination for large volumes.

Response fields:

Warning: page/limit and cursor are mutually exclusive. Sending both in the same request returns 422 Unprocessable Content. For large datasets where total_items would be impractical to compute, the field may be null or an estimate — use has_more instead as your continuation signal.

Field projection (fields)

Endpoints that support fields return only the requested subset of the canonical model, reducing payload size.

Usage:

GET /api/v2/pam/credentials/101?fields=credential.username,device.name,jit.credential_enabled

Rules:

• Use dot notation to reference nested fields (e.g., credential.username, device.tags).
• Request a full object by naming it without a child path (e.g., fields=device returns all non-sensitive device fields).
• When fields is omitted, all public fields of the canonical model are returned, with null for fields that aren't applicable.
• Fields not present in the canonical model return 422 with code api.fields.invalid.
• Sensitive fields return 403 with code api.fields.sensitive.not.allowed. See Sensitive fields.
• Fields outside the scope of the current authorization return 403.

Sensitive fields — never returned:

The following fields are permanently excluded from all responses. Requesting them returns 403:

• credential.password
• certificate.key_file
• certificate.key_password
• totp.secret_key

Sorting (sort_by)

List endpoints that support sorting accept the sort_by query parameter.

Usage:

GET /api/v2/pam/credentials?sort_by=criticality:desc,credential.username

Rules:

Filters

List endpoints accept filter parameters as query strings. All filter parameters are optional.

AND and OR logic

Note: The pipe character (|) is not supported as an OR separator. Use comma-separated values instead.

Boolean filter values

Boolean parameters accept only true or false as string values. The values 0, 1, yes, and no are not accepted and return 422.

Validation

All invalid filter parameters return an explicit error — the API never silently ignores an unrecognized filter.

Examples

Exact match:

GET /api/v2/pam/credentials?credential.username=svc-payments

AND — multiple fields:

GET /api/v2/pam/credentials?device_id=123&credential.criticality=high&jit.credential_enabled=true

AND — same field (array):

GET /api/v2/pam/credentials?credential.tags=prod&credential.tags=finance

OR — comma-separated values:

GET /api/v2/pam/credentials?credential.criticality=high,medium

Multi-field sort:

GET /api/v2/pam/credentials?sort_by=criticality:desc,credential.username

Naming conventions

All v2 API endpoints follow these conventions consistently.

Authentication errors

The following authentication errors apply to all v2 endpoints.

Related documents

• GET | List all credentials (v2)
• GET | List a credential by [id] (v2)
• About applications and authorizations in A2A