Skip to main content

​
What It Does

The Credentials API provides RPCs for creating, revoking, and rotating API credentials used by external integrations to authenticate with MintID.

​
Who It’s For

Brand administrators and developers who manage programmatic access to the MintID platform.

​
create_api_credential_record

​
What it does

Creates a new API credential for the specified brand. The caller provides a client ID and a hashed client secret — plaintext secrets are never sent to or stored by the server.

​
Request

{
  "_brand_id": "b1a2c3d4-0000-0000-0000-000000000001",
  "_name": "ERP Sync - Production",
  "_client_id": "client_abc123",
  "_client_secret_hash": "<hashed-value>",
  "_scopes": ["products:read", "products:write"],
  "_metadata": { "integration": "erp", "environment": "production" },
  "_expires_at": "2027-01-01T00:00:00Z"
}

​
Response (example)

{
  "ok": true
}

​
Errors (examples)

  • Not authenticated — request has no valid JWT or the token has expired.
  • Forbidden — caller does not have admin or owner access to the specified brand.
  • Invalid input — missing required fields or invalid parameter values.

​
revoke_api_credential_record

​
What it does

Permanently revokes an API credential. Revoked credentials can no longer authenticate. Revocation cannot be undone — create a new credential if access is needed again.

​
Request

{
  "_brand_id": "b1a2c3d4-0000-0000-0000-000000000001",
  "_credential_id": "c1a2c3d4-0000-0000-0000-000000000001",
  "_reason": "Rotating credentials for security review"
}

​
Response (example)

{
  "ok": true
}

​
Errors (examples)

  • Not authenticated — request has no valid JWT or the token has expired.
  • Forbidden — caller does not have admin or owner access to the specified brand.
  • Invalid input — credential ID not found or request is malformed.

​
rotate_api_credential_secret_record

​
What it does

Replaces the secret hash on an existing credential without revoking it. The credential remains active with the new secret. Cannot be used on revoked credentials.

​
Request

{
  "_brand_id": "b1a2c3d4-0000-0000-0000-000000000001",
  "_credential_id": "c1a2c3d4-0000-0000-0000-000000000001",
  "_new_secret_hash": "<new-hashed-value>",
  "_reason": "Scheduled quarterly rotation"
}

​
Response (example)

{
  "ok": true
}

​
Errors (examples)

  • Not authenticated — request has no valid JWT.
  • Forbidden — caller does not have sufficient access for this operation.
  • Invalid input — request is malformed or cannot be processed.

​
Limits & Notes

  • All credential RPCs require authentication with admin or owner role.
  • Client secrets are never stored in plaintext — only hashed values are accepted.
  • Revocation is permanent and cannot be undone.
  • Rotation updates the secret without changing the client ID or metadata.
  • Credentials can optionally have an expiry date; expired credentials are treated as inactive.

​
FAQ

Can I see the client secret after creation? No. The plaintext secret is available only at the moment of creation in the UI. The API accepts only hashed values. Can I reactivate a revoked credential? No. Revocation is permanent. Create a new credential if access is needed again.