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#
- Sign in to the Orchestrator web app.
- Open your profile menu, choose My account, then Security.
- Under Access tokens, create a new token. Give it a name that says where it will be used, for example
ci-invoices-publish. - 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.createandpackages.vieware enough. - Copy the token. It starts with
vpx_pat_and is shown only once. - 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)HTTPCopyPOST /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:
LinuxWindowsBashCopycurl -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:
HTTPCopyAuthorization: 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):
- The app opens
https://orchestrator.example.com/oauth/authorizein your browser. - You sign in (with MFA or a passkey if your account uses them) and approve the request.
- 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):
- The tool calls
POST /api/v1/device/codeand receives a device code and a short user code. - You open the Orchestrator's
/devicepage, sign in, and approve the request for one tenant, or deny it. - The tool polls
POST /api/v1/device/token. It receives400withauthorization_pendingorslow_downuntil you approve, then an access token. Other answers areaccess_denied,expired_tokenandinvalid_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:
- An administrator with
settings.editopens Tenant settings > External applications and creates an application. - They choose its permissions (scopes). An application never gets more than its creator holds, has no role and belongs to no workspace.
- 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:
BashCopycurl -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_KEYor 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