TrueVault Identity Manager

Submit a credential for a person

POST /credentials/submit

Submit a credential document for verification and transformation into a W3C Verifiable Credential. The credential will be processed, signed, and stored according to the OpenBadges 3.0 standard.

The API supports different types of credentials, each with its own metadata structure.

Credential Types

ACIC NCCHC (Australian Criminal Intelligence Commission - Nationally Coordinated Criminal History Check)

  • Type: acicncchc
  • Description: A nationally coordinated criminal history check certificate
  • Metadata Structure: As per NSS result specification

Response

On success, the API returns a reference to the created credential which can be used to retrieve or verify the credential later. The credential is issued as a JWT (JSON Web Token) that can be verified using the TrueVault public key as disclosed in the JWT header iss field.

Security

  • Credentials are signed using RSA keys
  • File uploads are scanned for malicious content
  • All sensitive data is encrypted at rest

Parameters

NameInRequiredDescription
Authorization header yes

Access key generated from the auth API

Example: Bearer 048c2a1c-0881-4dcc-bfca-ccccccccc51

Request body

Content type application/json

Fields

FieldTypeRequiredDescription
type string yes

Type of the credential. Determines the expected metadata structure and validation rules.

Supported types:

  • acicncchc: Australian Criminal Intelligence Commission - National Criminal History Check

Note: More credential types will be added in future updates.

One of: acicncchc
person_ref string yes

Reference to the person in UID format '
name string yes

Display name for the credential (not required for type acicncchc)
description string yes

Description of the credential (not required for type acicncchc)
metadata object no

The raw credential data specific to the credential type.

For type acicncchc, this must be in the standard NSS result format
file_data string yes

Base64 encoded file data (PNG, JPG, or PDF) for the original document / certificate
file_name string yes

Name of the source file, with correct extension
issuer_name string yes

Name of the credential issuer (Your company)
issuer_url string yes

URL of the credential issuer (Your company website or specific product URL)
issuer_ref string yes

Reference ID from the issuer (Your company's public ID for this specific credential)
time_expires integer yes

Unix timestamp when the credential expires (not required for type acicncchc)

Example request body

{
  "type": "acicncchc",
  "person_ref": "ab544aa0-e90c-555a-a987-799c0e7f2992/63cf65d5-e5dd-5c64-bad9-158a8b8b3ac0",
  "name": "Professional Certification",
  "description": "Issued for completion of professional certification",
  "file_data": "string",
  "file_name": "credential.pdf",
  "issuer_name": "TrueVault",
  "issuer_url": "https://example.com/issuer",
  "issuer_ref": "check-12345",
  "time_expires": 1893456000
}

Responses

StatusDescription
200 OK

Credential submitted successfully

400 Bad Request

Invalid request parameters

401 Unauthorized

Unauthorized - Invalid or missing authentication

409 Conflict

Duplicate credential already exists

413 Payload Too Large

File too large (max 5MB)

422 Unprocessable Entity

Validation error

Content type application/json

Response fields (200)

FieldTypeRequiredDescription
data object no

The reference for the submitted credential, returned in the credential_ref field. It is an opaque value: store it as returned and append it unchanged to the verify, file-data and revoke paths. Do not parse it or build one yourself, as its internal structure is not part of the contract and may change. The credential itself is returned as a JWT (JSON Web Token) that can be verified using the issuer's public key, available at baric/credential/keys/{credential_type}/{person_uid}/{credential_uid}.
correlation_id string no

Example 200 response

{
  "data": {
    "credential_ref": "0d8f1e2a-6c31-4a51-9f0e-2b7c4d8e1f33/9a8b7c6d-1e2f-4a3b-8c9d-0e1f2a3b4c5d"
  },
  "correlation_id": "string"
}

Content type application/json

Error (400, 409, 413, 422)

FieldTypeRequiredDescription
error object no
error.message string yes

Human-readable error message
error.code string yes

Machine-readable error code

One of: E1001, E1002, E1003, E1004, E1005, E1006, E1007, E1008, E1009, E1010, E1011, E1012, E2001, E2002, E2003, E2004, E2005
error.type string yes

Error type identifier

One of: VALIDATION_ERROR, INVALID_REQUEST, AUTHENTICATION_FAILED, UNAUTHORIZED, NOT_FOUND, CONFLICT, RATE_LIMIT_EXCEEDED, PRECONDITION_FAILED, CREDENTIAL_EXPIRED, CREDENTIAL_REVOKED, CREDENTIAL_PENDING_ACCEPTANCE, CREDENTIAL_VERIFICATION_FAILED, INTERNAL_ERROR, INTERNAL_ERROR_EMAIL, DATABASE_ERROR, EXTERNAL_SERVICE_ERROR, SERVICE_UNAVAILABLE
error.timestamp string yes
error.correlation_id string no
error.details object no

Additional error context

Example 400 response

{
  "error": {
    "message": "Invalid phone number format",
    "code": "E1001",
    "type": "VALIDATION_ERROR",
    "timestamp": "2024-02-20T03:14:15Z",
    "correlation_id": "req_1234567890",
    "details": {
      "validation_errors": {
        "phone": "Must be in format +61423123456"
      }
    }
  }
}

Example request

curl --request POST \
  --url https://api.sandbox.truevault.com.au/api/v1/credentials/submit \
  --header 'Authorization: <value>' \
  --header 'Content-Type: application/json'