1. JWT Token

When authenticating with the Vertex API, you'll receive a JSON Web Token (JWT). This token is crucial for making authenticated requests to the API.

1.1 JWT Structure

A JWT consists of three parts, each separated by a dot (.):

1. Header
2. Payload
3. Signature

These parts are encoded separately and concatenated using periods to produce the final token.

The JSON you receive and use in your application is the decoded payload part of the JWT. Here's an example of a decoded payload:

{
  "jti": "HYILNHJ5TAILSLXYSWXMGFLEOGQVIXPW4VXJAO2WSSWQBDPTDJHQ",
  "iat": 1741272289,
  "iss": "ABPMW6SJ6SBPR5OEAIZGANDBNLMOOOBMTTLVIACABYAMTU5SUYY6UY2R",
  "name": "partner-bridgelabs",
  "sub": "UA5SKV2KRSYTHK3Q36T6F5YYGVQXRKZWJZPBNY6RDP7BL7IMKIIBNOAQ",
  "nats": {
    "pub": {},
    "sub": {},
    "issuer_account": "AAQLOMWDVSG4A53KHIUX6UMXPAQYWAK3POMVIN4I7NHWVXOLZTI7N6WO",
    "tags": [
      "partner:52c844f1-17b3-4aa5-9a59-f4f7eaca22c3"
    ],
    "type": "user",
    "version": 2
  }
}

Key components of the payload:

• jti: JWT ID
• iat: Issued at time
• iss: Issuer
• name: User identifier
• sub: Subject
• nats: NATS-specific information, including user details and tags. Tags provide additional information about the user.

1.2 Using the JWT

When making API requests, you'll use the encoded JWT in the Nats message header with the key token authorisation:

token: <jwt_token>

2. Base Subject for API Calls

The base subject for API calls follows this structure:

svc.<service-prefix>.<[partner-id]>.<endpoint>

For example:

svc.kyb.123e4567-e89b-12d3-a456-426614174000.get

The organisation ID in the subject influences the endpoint, allowing for organization specific operations.

3. Document Uploads

When uploading documents for KYB (Know Your Business) processes, the API expects specific document types. Here's how the document upload process works:

1. Prepare the document files.
2. Generate unique names for each document (explained in the next section).
3. Use the appropriate API endpoint to upload the documents.
4. The API will process and store these documents securely.

3.1 Document Naming Convention

Document names follow a specific structure:

<document_type>_<identifier?>_<timestamp>

Examples:

business_registration_1726220326
proof_of_address_1726220276
tax_verification_1726220240
director_proof_of_address_7aa53a6d5869c8145cee2af0f5d92aa5_1726220179
director_selfie_7aa53a6d5869c8145cee2af0f5d92aa5_1726220125
director_id_back_7aa53a6d5869c8145cee2af0f5d92aa5_1726220059
director_id_front_7aa53a6d5869c8145cee2af0f5d92aa5_1726220044

The identifier part (e.g., 7aa53a6d5869c8145cee2af0f5d92aa5) is an MD5 hash, generated from unique information about the director or document to ensure uniqueness and privacy.

3.2 Document Types

The API recognizes several document types, including:

• Business registration
• Proof of address
• Tax verification
• Director specific documents (proof of address, selfie, ID front/back)

When uploading documents, ensure that you follow this naming convention and use the appropriate document types as required by the KYB process.

Formats

• Dates - All dates are formatted in RFC 3339 unless otherwise stated. This format is mostly interchangeable with ISO8601 format
• Monetary values - in requests are expected to be an integer in cents, however responses will provide a string representation which includes the currency symbol.
• Phone numbers - all phone numbers are expected to include the country code unless otherwise expected (eg. 27763456789)

By understanding these API essentials, you'll be better equipped to interact with the Vertex API, handle authentication, make organization specific calls, and manage document uploads effectively.