Authentication and connecting a customer

Every call to the Vort Partner API is made from your server, with two secrets that never leave it. RFC 2119 keywords apply.

Two secrets

Secret	Format	Identifies	Header	Sent on
Partner API key	`vpk_live_` + 48 hex	You, the vendor	`x-partner-key`	every request
Org token	`vot_` + 48 hex	One customer organization	`x-vort-org`	every request except `/activations/redeem`

Every call is server-to-server. A Vort key or org token MUST NOT reach a browser, a mobile app, a log line visible to customers, a URL, or a frontend bundle. Certification checks for the strings vpk_ and vot_ in your frontend bundle and browser network traffic (item C-02).

Vort stores only SHA-256 hashes of both secrets. A lost org token cannot be recovered: ask Vort for a new activation code and redeem it.
The acting recruiter is identified by acting_user_external_id in the request body. It is a field, not a credential. Your server is responsible for making sure the logged-in user in your product is who you say they are.
Key rotation: Vort can rotate your partner key on request. The old key stops working the moment the new one is issued (there is no overlap window), so plan the rotation with Vort and deploy the new key immediately.
Webhook secret: Vort sends you a webhook signing secret out of band. It is distinct from your API key (see Webhooks).

Request headers

string

required

Your partner API key, vpk_live_ + 48 lowercase hex. Sent on every request.

string

The customer’s org token, vot_ + 48 lowercase hex, obtained by redeeming an activation code. Required on every request except POST /activations/redeem.

string

he or en. Language of notices and messages for this request. Default: your partner default (he unless agreed otherwise).

string

application/json on every POST.

A request with a missing or unknown key gets 401 invalid_partner_key; a missing or unknown org token gets 401 invalid_org_token. See Errors.

Connecting a customer

A customer organization is connected once, by one of its admins, with a one-time activation code that Vort issues to that customer.

 Customer admin                 Your frontend              Your server                      Vort
 receives VORT-XXXX-XXXX  ───▶  "Connect Vort" form  ───▶  POST /activations/redeem  ───▶   200 {org_token, organization_name}
                                shows organization_name ◀─ stores org_token (encrypted, server side)

The admin pastes the code

The admin pastes the code into your Connect Vort screen (see Screen 1 in the UI specification). The form posts to your server; the browser never talks to Vort.

Your server redeems it

Your server calls POST /activations/redeem with the code and your id for this customer (external_id, unique per partner). Only x-partner-key is sent.

Store the org token

Vort returns the org token once. Store it server-side, encrypted at rest, keyed by your external_id. Vort cannot show it again.

Show the connected state

Your screen shows the connected state with organization_name, never the token.

The code format is VORT-XXXX-XXXX using the alphabet ABCDEFGHJKMNPQRSTUVWXYZ23456789 (no 0, O, 1, I, L). Codes are valid 14 days by default. Vort normalizes case, spaces and dashes, so vort xxxx xxxx is accepted. Send what the user typed; you MAY trim it.

curl -sS -X POST "$VORT_BASE/activations/redeem" \
  -H "x-partner-key: $VORT_PARTNER_KEY" \
  -H "Content-Type: application/json" \
  -d '{"code":"VORT-7KQM-3XHP","external_id":"hrmony-tenant-5521"}'

const res = await fetch(`${process.env.VORT_BASE}/activations/redeem`, {
  method: "POST",
  headers: {
    "x-partner-key": process.env.VORT_PARTNER_KEY,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ code: codeTypedByAdmin.trim(), external_id: "hrmony-tenant-5521" }),
});
const data = await res.json();
// 200: store data.org_token encrypted, server side. Return only data.organization_name to the browser.

import os
import requests

res = requests.post(
    f"{os.environ['VORT_BASE']}/activations/redeem",
    headers={"x-partner-key": os.environ["VORT_PARTNER_KEY"]},
    json={"code": code_typed_by_admin.strip(), "external_id": "hrmony-tenant-5521"},
    timeout=20,
)
data = res.json()
# 200: store data["org_token"] encrypted, server side. Return only data["organization_name"] to the browser.

use Illuminate\Support\Facades\Http;

$res = Http::withHeaders(['x-partner-key' => config('services.vort.partner_key')])
    ->acceptJson()
    ->timeout(20)
    ->post(config('services.vort.base') . '/activations/redeem', [
        'code' => trim($request->input('code')),
        'external_id' => 'hrmony-tenant-5521',
    ]);
// 200: store $res->json('org_token') encrypted, server side. Return only organization_name to the browser.

Response

{
  "organization_id": "0b8f4a52-2d1e-4c7b-9a61-5f0e3c2d9b17",
  "org_token": "vot_9c1e...<48 hex total>",
  "organization_name": "Acme Staffing Ltd"
}

Redeem errors

HTTP	`error`	Show the admin
404	`code_not_found`	The API `message`, under the input.
409	`code_already_redeemed` (+ `redeemed_at`)	The API `message`, under the input.
410	`code_expired`	The API `message`, under the input.
409	`external_id_taken`	That this workspace is already connected, and to contact Vort.

POST /activations/redeem is not safe to retry blindly: the code is single-use and the token is not returned a second time. If the first response was lost (for example, a timeout), ask Vort for a new activation code.

Reconnecting

On 401 invalid_org_token from any later call, show the Connect Vort screen again in the disconnected state, with a note that the connection must be renewed. The admin redeems a new code from Vort. On 403 organization_disabled, tell the admin their Vort connection is paused and to contact Vort.

Registering recruiters

Before a recruiter starts a run, register them with POST /users, using your own id for them:

curl

curl -sS -X POST "$VORT_BASE/users" \
  -H "x-partner-key: $VORT_PARTNER_KEY" \
  -H "x-vort-org: $VORT_ORG" \
  -H "Content-Type: application/json" \
  -d '{"external_id":"u-88121","email":"dana@acme-staffing.example","full_name":"Dana Levi","role":"recruiter"}'

The recruiter is registered as an API-only identity of this organization. The email is stored as a contact and display e-mail only: it is not a login, no Vort account is created or linked under it, and nothing is e-mailed to the recruiter. Recruiters registered this way cannot sign in to Vort directly.
Later calls name the recruiter with acting_user_external_id. An unregistered id is rejected with 404 user_not_found.
POST /users is an upsert on external_id and is safe to retry.

Full request and response schema: Register a recruiter.

Server checklist

Partner key in your secrets manager or environment, never in source control.
Org tokens encrypted at rest, one per connected customer, readable only by the service that calls Vort.
No key or token in browser responses, browser storage, URLs, logs visible to customers, or error messages.
Base URL in configuration, one value per environment (sandbox and production).
When you contact Vort, identify the key by its first 12 characters only (for example vpk_live_3f9).

Get started

Build the integration

Authentication and connecting a customer

Two secrets

Request headers

Connecting a customer

Redeem errors

Reconnecting

Registering recruiters

Server checklist

​Two secrets

​Request headers

​Connecting a customer

​Redeem errors

​Reconnecting

​Registering recruiters

​Server checklist

Two secrets

Request headers

Connecting a customer

Redeem errors

Reconnecting

Registering recruiters

Server checklist