Authentication

Create a personal access token, call the API with it, and understand the other credentials VeloPhex uses.

Scripts, CI pipelines and integrations authenticate to the Orchestrator API with a personal access token (PAT). This page shows you how to create one, how to send it, and how the other credentials in the platform relate to it.

Credential types at a glance#

Credential Prefix Issued to Used for
Web session (cookie) A person signed in to the web app The web app itself
Personal access token vpx_pat_ A person, for one tenant Scripts, CI, the Python CLI, the package feed
Desktop sign-in vpx_pat_ plus a refresh token A person signed in to Studio or the Assistant Studio and the Assistant, renewed automatically
External application token (JWT) An application registered in a tenant Server-to-server integrations
Execution token vpx_rt_ One running job attempt The runtime API, only while that attempt runs
Enrollment key vpx_ek_ A machine, once Enrolling a Robot (single use)
Machine access token (JWT) An enrolled machine The Robot API, obtained with the machine's private key

You create personal access tokens yourself, and an administrator registers external applications. The others are created by the platform for a specific purpose. See Robot identity and tokens for the machine side.

Create a personal access token#

Prerequisites#

  • An account in the tenant with the permissions your integration needs.
  • The tenant id (shown on the tenant settings page).

Steps#

  1. Sign in to the Orchestrator web app.
  2. Open your profile menu, choose My account, then Security.
  3. Under Access tokens, create a new token. Give it a name that says where it will be used, for example ci-invoices-publish.
  4. Choose the tenant, the permissions and the lifetime (1 to 365 days). You can only grant permissions you hold yourself, so pick only what the integration needs. For publishing packages, packages.create and packages.view are enough.
  5. Copy the token. It starts with vpx_pat_ and is shown only once.
  6. Store it in your secret store or CI secret variables. Never commit it to source control.

You can also create a token from an existing web session with the API:

Create a token (web session only)HTTPCopy
POST /api/v1/me/access-tokens HTTP/1.1
Content-Type: application/json

{
  "tenantId": "7f9c2b18-1c4e-4f7a-9a51-2b1f0c3d4e5f",
  "name": "ci-invoices-publish",
  "permissions": ["packages.view", "packages.create"],
  "expiresInDays": 90
}

The 201 Created response contains details (id, name, display prefix, permissions, creation and expiry times) and token, the secret value. GET /api/v1/me/access-tokens lists your tokens without their values, and DELETE /api/v1/me/access-tokens/{tokenId} revokes one. You can hold at most 50 tokens.

A token cannot be shown again

The Orchestrator stores only a keyed hash of each token. If you lose a token, revoke it and create a new one.

Verify#

Call an endpoint the token is allowed to use:

LinuxWindowsBashCopy
curl -s -H "Authorization: Bearer $VELOPHEX_API_KEY" \
  "https://orchestrator.example.com/api/v1/tenants/$TENANT_ID/packages?page=1&pageSize=10"
PowerShellCopy
$headers = @{ Authorization = "Bearer $env:VELOPHEX_API_KEY" }
Invoke-RestMethod -Headers $headers `
  -Uri "https://orchestrator.example.com/api/v1/tenants/$env:TENANT_ID/packages?page=1&pageSize=10"

You should see a JSON object with an items array. A 401 means the token is wrong, expired or revoked. A 403 with the code permission_required names the permission the token lacks. A 404 for the whole tenant usually means the token was issued for a different tenant.

Sending the token#

On management API routes, send the token as a bearer token:

HTTPCopy
Authorization: Bearer vpx_pat_...

The package feed also accepts two forms that NuGet clients use:

Form Used by
Authorization: Bearer vpx_pat_… Studio
Basic authentication with the token as the password (any user name) NuGet clients reading the feed
X-NuGet-ApiKey: vpx_pat_… dotnet nuget push --api-key, velophex publish

Basic authentication and X-NuGet-ApiKey are accepted on feed routes only. A feed request without credentials gets 401 with WWW-Authenticate: Basic, which prompts NuGet clients to send stored credentials. Reading the feed needs packages.view; pushing needs packages.create.

Sign-in for Studio and the Assistant#

Studio and the Assistant sign you in through your system browser with the OAuth 2.0 authorization code flow and PKCE, on a loopback redirect (a free port from 48620 to 48639):

  1. The app opens https://orchestrator.example.com/oauth/authorize in your browser.
  2. You sign in (with MFA or a passkey if your account uses them) and approve the request.
  3. The browser returns to the app, which exchanges the code at POST /api/v1/oauth/token.

The browser step times out after five minutes (VEL-AUTH-408-001). The app receives a short-lived access token and a rotating refresh token, stores them in Windows Credential Manager for your Windows account, and renews the access token on its own. Studio refuses to send a token over plain http to anything other than localhost. See Sign in to Orchestrator.

Device sign-in#

For tools that cannot receive a browser redirect, the Orchestrator also supports the OAuth 2.0 device authorization grant (RFC 8628):

  1. The tool calls POST /api/v1/device/code and receives a device code and a short user code.
  2. You open the Orchestrator's /device page, sign in, and approve the request for one tenant, or deny it.
  3. The tool polls POST /api/v1/device/token. It receives 400 with authorization_pending or slow_down until you approve, then an access token. Other answers are access_denied, expired_token and invalid_grant.

External applications (client credentials)#

A server-to-server integration that should not depend on one person's account can be registered as an external application:

  1. An administrator with settings.edit opens Tenant settings > External applications and creates an application.
  2. They choose its permissions (scopes). An application never gets more than its creator holds, has no role and belongs to no workspace.
  3. The client secret is shown once. Rotating it replaces the old secret at once.

The integration then requests a token with the client credentials grant:

BashCopy
curl -u "$CLIENT_ID:$CLIENT_SECRET" \
  -d grant_type=client_credentials -d "scope=queues.view" \
  https://orchestrator.example.com/api/v1/oauth/token

The token is a JWT, valid for one hour by default, for the /api/v1/tenants/{tenantId}/... routes of that tenant only. Send it as Authorization: Bearer <token>. Creating, rotating and revoking an application, and every token issued, are recorded in the audit log.

Web sessions#

The web app signs in with POST /api/v1/auth/login (user name or email plus password, then an MFA code or passkey when the account needs one) and receives an HttpOnly, Secure, SameSite=Strict session cookie with a fixed lifetime (12 hours by default). Passkey sign-in and single sign-on providers end in the same session. State-changing requests from the browser also need the antiforgery token from GET /api/v1/auth/antiforgery. Account lockout and password rules apply. You rarely need this flow outside a browser; use a personal access token or an external application for automation.

Good practice#

  • Create one token per integration so you can revoke it without breaking others.
  • Give each token the smallest permission set and a short lifetime, and rotate it before it expires.
  • Pass tokens through environment variables or standard input. The Python CLI reads its token from VELOPHEX_API_KEY or standard input and deliberately refuses one on the command line.
  • Revoke tokens when a person leaves or a pipeline is retired. Tokens are also invalidated if an operator rotates the platform token pepper.

Next steps#

Credential types at a glance

Create a personal access token

Prerequisites

Steps

Verify

Sending the token

Sign-in for Studio and the Assistant

Device sign-in

External applications (client credentials)

Web sessions

Good practice

Next steps