Authentication
Protected API V2 endpoints take a short-lived access token issued by API V2's own authorization system, sent as a bearer token.
No API V2 access token can be obtained today, so protected endpoints cannot be used yet. A request with a token currently receives an error, see What happens today. Sign-in, application registration and access scopes are being designed and are not promised for any date.
API V2 is independent of API V1. Tokens, developer keys and registered applications of API V1 are not accepted by API V2 and keep serving API V1 only. Existing applications continue to use API V1 until they are migrated (see the API V1 documentation).
How API V2 authentication works
An API V2 access token is a bearer token with these properties:
- Issued to a user through a registered application. It identifies who the request is for and which application made it, never a password or a shared key.
- Short-lived. Tokens are valid for a few minutes. Longer sessions are renewed through revocable sessions, so a stolen token stops working quickly and a user can sign out an application at any time.
- Limited by scopes. The token states what the application may do for the user. A request outside the token's scopes is refused.
- Bound to one environment. A token issued for the Test API is rejected by the Production API, and the reverse.
Treat a token as an opaque string and never parse it in your application.
Using an access token
Send the token in the Authorization header of requests to a protected endpoint:
curl https://apiv2.virtualperformancetool.com/v2/me \
-H "Authorization: Bearer $VPT_TOKEN"
GET /v2/me describes the token it receives: the user, the application, the granted scopes and the expiry.
GET /v2/health and GET /v2/openapi.json need no token. Protected endpoints are marked as requiring authentication in the
API reference.
What happens today
Because sign-in does not exist yet, the answers you can see are:
| Request | Status | Error code |
|---|---|---|
| Protected endpoint without a token | 401 | authentication_required |
| Protected endpoint with any token | 503 | authentication_unavailable |
Once API V2 authentication is available, a token that is not a valid API V2 access token, including any API V1 token or developer key, receives
401 with invalid_token. See Errors for the full list and what to do about each.
Developer access
How applications are registered, how users authorize them and which scopes and data detail an application can receive are being designed for API V2. Nothing is available yet: there is no registration, no application credentials and no authorization page. This page will describe each of them when it is implemented.
Keeping tokens safe
- Treat a token like a password. Anyone who has it can act as the user until it expires or is revoked.
- Send tokens only to the API servers listed in the introduction, over HTTPS. This documentation site never needs them.
- Never put a token in a URL, and never log it.
- The API reference runs entirely in your browser. It sends requests straight to the API server you selected, keeps the token in memory only (it is gone when you reload the page) and does not use any third-party proxy.