{"templateId":"markdown","sharedDataIds":{"sidebar":"sidebar-sidebars.yaml"},"props":{"metadata":{"markdoc":{"tagList":["tabs","tab","code-snippet","partial"]},"type":"markdown"},"seo":{"title":"Authentication and tokens"},"dynamicMarkdocComponents":[],"compilationErrors":[],"ast":{"$$mdtype":"Tag","name":"article","attributes":{},"children":[{"$$mdtype":"Tag","name":"Heading","attributes":{"level":1,"id":"authentication-and-tokens","__idx":0},"children":["Authentication and tokens"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["This page is for developers building an integration that calls VBAPI for longer than a single script run. It explains the login flow, the challenges login can return, how to send and reuse the ID token, and how to keep credentials safe."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"the-flow","__idx":1},"children":["The flow"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["VBAPI uses two steps. You log in once with your username and password and receive tokens. You then send the ID token as a Bearer token on every other call until it expires."]},{"$$mdtype":"Tag","name":"Diagram","attributes":{"data-language":"mermaid","diagramType":"mermaid","diagramSource":"sequenceDiagram\n autonumber\n participant C as Your integration\n participant V as VBAPI\n C->>V: POST /user-authentication
Basic username:password, x-api-key,
client ID, client code, database, User-Agent\n alt Tokens returned\n V-->>C: data.authenticationResult
(idToken, accessToken, refreshToken, expiresIn)\n else Challenge returned\n V-->>C: data.challengeName and data.session\n alt NEW_PASSWORD_REQUIRED\n C->>V: POST /change-temporary-password
(userID, newPassword, session)\n else Multi-factor code required\n C->>V: POST /mfa-submit-code
(username, mfaCode, session)\n end\n V-->>C: authenticationResult, or another challenge\n end\n loop Until expiresIn runs out\n C->>V: Any call with Authorization: Bearer idToken\n V-->>C: Response\n end\n C->>V: Log in again (POST /user-authentication)
or POST /user-refresh-tokens\n","diagramHtml":"VBAPIYour integrationVBAPIYour integrationalt[NEW_PASSWORD_REQUIRED][Multi-factor code required]alt[Tokens returned][Challenge returned]loop[Until expiresIn runs out]POST /user-authenticationBasic username:password, x-api-key,client ID, client code, database, User-Agent1data.authenticationResult(idToken, accessToken, refreshToken, expiresIn)2data.challengeName and data.session3POST /change-temporary-password(userID, newPassword, session)4POST /mfa-submit-code(username, mfaCode, session)5authenticationResult, or another challenge6Any call with Authorization: Bearer idToken7Response8Log in again (POST /user-authentication)or POST /user-refresh-tokens9","diagramHtmlDark":"VBAPIYour integrationVBAPIYour integrationalt[NEW_PASSWORD_REQUIRED][Multi-factor code required]alt[Tokens returned][Challenge returned]loop[Until expiresIn runs out]POST /user-authenticationBasic username:password, x-api-key,client ID, client code, database, User-Agent1data.authenticationResult(idToken, accessToken, refreshToken, expiresIn)2data.challengeName and data.session3POST /change-temporary-password(userID, newPassword, session)4POST /mfa-submit-code(username, mfaCode, session)5authenticationResult, or another challenge6Any call with Authorization: Bearer idToken7Response8Log in again (POST /user-authentication)or POST /user-refresh-tokens9"},"children":["sequenceDiagram\n autonumber\n participant C as Your integration\n participant V as VBAPI\n C->>V: POST /user-authentication
Basic username:password, x-api-key,
client ID, client code, database, User-Agent\n alt Tokens returned\n V-->>C: data.authenticationResult
(idToken, accessToken, refreshToken, expiresIn)\n else Challenge returned\n V-->>C: data.challengeName and data.session\n alt NEW_PASSWORD_REQUIRED\n C->>V: POST /change-temporary-password
(userID, newPassword, session)\n else Multi-factor code required\n C->>V: POST /mfa-submit-code
(username, mfaCode, session)\n end\n V-->>C: authenticationResult, or another challenge\n end\n loop Until expiresIn runs out\n C->>V: Any call with Authorization: Bearer idToken\n V-->>C: Response\n end\n C->>V: Log in again (POST /user-authentication)
or POST /user-refresh-tokens\n"]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"log-in","__idx":2},"children":["Log in"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/openapi/vbasoftware/vbasoftware.api/user/userauthentication"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["POST /user-authentication"]}]}," has no body. It reads your username and password from a Basic ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Authorization"]}," header and needs these headers:"]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Header"},"children":["Header"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Value"},"children":["Value"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["x-api-key"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Your API key."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Authorization"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Basic "]},"."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["vbasoftware-client-id"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Your client ID."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["vbasoftware-client-code"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Your client code."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["vbasoftware-database"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["The database to log in to, for example ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["YOUR_DATABASE"]},"."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["vbasoftware-machine-id"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Optional. An identifier for the calling machine."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["User-Agent"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Recommended: your integration name, for example ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["YourCompany-Integration/1.0"]},"."]}]}]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The shared client used by the samples logs in like this:"]},{"$$mdtype":"Tag","name":"Tabs","attributes":{"size":"medium"},"children":[{"$$mdtype":"Tag","name":"TabItemFragment","attributes":{"label":"C#","disable":false},"children":[{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"file":"../../_samples/_shared/csharp/VbapiClient.cs","language":"csharp","header":{"controls":{"copy":{}}},"lang":"csharp","source":" public async Task AuthenticateAsync()\n {\n using var request = new HttpRequestMessage(HttpMethod.Post, $\"{_baseUrl}/user-authentication\");\n var basic = Convert.ToBase64String(Encoding.UTF8.GetBytes($\"{_username}:{_password}\"));\n request.Headers.Authorization = new AuthenticationHeaderValue(\"Basic\", basic);\n request.Headers.Add(\"x-api-key\", _apiKey);\n request.Headers.Add(\"vbasoftware-client-id\", _clientId);\n request.Headers.Add(\"vbasoftware-client-code\", _clientCode);\n request.Headers.Add(\"vbasoftware-database\", _database);\n request.Headers.UserAgent.ParseAdd(_userAgent);\n\n using var response = await _http.SendAsync(request);\n var body = await ReadJsonAsync(response);\n if (response.StatusCode != HttpStatusCode.OK)\n throw new VbapiException(response.StatusCode, body?[\"error\"], body?[\"debug\"]?[\"activityID\"]?.GetValue());\n\n var login = body![\"data\"]!;\n var challenge = login[\"challengeName\"]?.GetValue();\n if (!string.IsNullOrEmpty(challenge))\n throw new VbapiChallengeException(challenge, login[\"session\"]?.GetValue());\n\n var result = login[\"authenticationResult\"]!;\n _idToken = result[\"idToken\"]!.GetValue();\n var expiresIn = result[\"expiresIn\"]?.GetValue() ?? 3600; // seconds\n _expiresAt = DateTimeOffset.UtcNow.AddSeconds(expiresIn - 60); // refresh one minute early\n }\n "},"children":[]}]},{"$$mdtype":"Tag","name":"TabItemFragment","attributes":{"label":"Python","disable":false},"children":[{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"file":"../../_samples/_shared/python/vbapi_client.py","language":"python","header":{"controls":{"copy":{}}},"lang":"python","source":" def authenticate(self):\n \"\"\"Log in with POST /user-authentication and keep the ID token until it expires.\"\"\"\n response = self.session.post(\n f\"{self.base_url}/user-authentication\",\n auth=(self.username, self.password), # HTTP Basic\n headers={\n \"x-api-key\": self.api_key,\n \"vbasoftware-client-id\": self.client_id,\n \"vbasoftware-client-code\": self.client_code,\n \"vbasoftware-database\": self.database,\n \"User-Agent\": self.user_agent,\n },\n timeout=30,\n )\n body = self._json(response)\n if response.status_code != 200:\n raise VbapiError(response.status_code, self._error(body), self._activity_id(body))\n\n login = body[\"data\"]\n if login.get(\"challengeName\"):\n raise VbapiChallengeError(login[\"challengeName\"], login.get(\"session\"))\n\n result = login[\"authenticationResult\"]\n self._id_token = result[\"idToken\"]\n # Refresh one minute early. expiresIn is in seconds.\n self._expires_at = time.time() + int(result.get(\"expiresIn\") or 3600) - 60\n "},"children":[]}]},{"$$mdtype":"Tag","name":"TabItemFragment","attributes":{"label":"TypeScript","disable":false},"children":[{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"file":"../../_samples/_shared/typescript/vbapiClient.ts","language":"typescript","header":{"controls":{"copy":{}}},"lang":"typescript","source":" async authenticate(): Promise {\n const response = await axios.post(`${this.baseUrl}/user-authentication`, null, {\n auth: { username: this.username, password: this.password }, // HTTP Basic\n headers: {\n \"x-api-key\": this.apiKey,\n \"vbasoftware-client-id\": this.clientId,\n \"vbasoftware-client-code\": this.clientCode,\n \"vbasoftware-database\": this.database,\n \"User-Agent\": this.userAgent,\n },\n validateStatus: () => true,\n });\n if (response.status !== 200) {\n throw new VbapiError(response.status, field(response.data, \"error\"), activityIdOf(response.data));\n }\n\n const login = response.data.data;\n if (login.challengeName) {\n throw new VbapiChallengeError(login.challengeName, login.session);\n }\n\n const result = login.authenticationResult;\n this.idToken = result.idToken;\n // Refresh one minute early. expiresIn is in seconds.\n this.expiresAt = Date.now() + ((result.expiresIn ?? 3600) - 60) * 1000;\n }\n "},"children":[]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["A successful login returns the tokens in ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["data.authenticationResult"]},". Example response (illustrative; the token values are fake and shortened, and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["expiresIn"]}," varies, so read it from each response):"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n \"data\": {\n \"challengeName\": null,\n \"session\": null,\n \"authenticationResult\": {\n \"accessToken\": \"eyJraWQiOiJET0NTIn0.fake-access-token\",\n \"idToken\": \"eyJraWQiOiJET0NTIn0.fake-id-token\",\n \"refreshToken\": \"fake-refresh-token\",\n \"expiresIn\": 3600\n }\n },\n \"error\": null,\n \"debug\": { \"activityID\": \"00000000-0000-0000-0000-000000000000\" }\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Send the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["idToken"]},", not the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["accessToken"]},", as ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Authorization: Bearer "]}," on every other call, together with ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["x-api-key"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["vbasoftware-database"]},", and a descriptive ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["User-Agent"]},"."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"handle-login-challenges","__idx":3},"children":["Handle login challenges"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Instead of tokens, login can return a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["challengeName"]}," and a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["session"]},", with ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["authenticationResult"]}," empty. Your code must check for this before it reads the token. The ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["session"]}," value ties the next call to this login attempt, so pass it back unchanged."]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Challenge"},"children":["Challenge"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"What it means"},"children":["What it means"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Next call"},"children":["Next call"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["NEW_PASSWORD_REQUIRED"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["The user still has a temporary password."]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/openapi/vbasoftware/vbasoftware.api/user/userchangetemppassword"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["POST /change-temporary-password"]}]}," with ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["userID"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["newPassword"]},", and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["session"]},"."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["A multi-factor challenge"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["The user must enter a code from their authenticator."]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/openapi/vbasoftware/vbasoftware.api/user/submitmfacode"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["POST /mfa-submit-code"]}]}," with ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["username"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["mfaCode"]},", and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["session"]},". It returns ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["202"]}," with the same response shape as a login."]}]}]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Both calls send ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["vbasoftware-client-id"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["vbasoftware-client-code"]},", and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["vbasoftware-database"]},", like login. Their responses have the same shape as a login response, so they can carry tokens or another challenge; check ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["challengeName"]}," again."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Example body for ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["POST /change-temporary-password"]}," (illustrative; values are fake):"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n \"userID\": \"DOCS-APIUSER\",\n \"newPassword\": \"a-new-strong-password\",\n \"session\": \"session-value-from-the-login-response\"\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["An unattended integration cannot answer a challenge by itself. The shared client stops with a clear message when login returns one. Complete the challenge once, by hand or with a small one-off script, and then run the integration again."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"reuse-the-token-until-it-expires","__idx":4},"children":["Reuse the token until it expires"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["expiresIn"]}," is the token's lifetime in seconds. Do not hard-code a lifetime; read ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["expiresIn"]}," from each login response."]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Log in once and reuse the ID token for every call until shortly before it expires. Do not log in for each request."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Share one client (and so one token) across your process rather than logging in from every worker."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Renew the token a little early. The shared client renews one minute before ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["expiresIn"]}," runs out."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["If a call returns ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["401"]}," anyway, log in again once and retry the call. The shared client does this; see ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/developer-portal/concepts/errors"},"children":["Errors and troubleshooting"]}," for the code."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The shared client keeps the token and its expiry time in memory and checks them before every call, as shown in the login code above."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"refresh-tokens","__idx":5},"children":["Refresh tokens"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Login also returns a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["refreshToken"]},". ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/openapi/vbasoftware/vbasoftware.api/user/refreshusertokens"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["POST /user-refresh-tokens"]}]}," exchanges it for new tokens. It takes the expired ID token in the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["expired-id-token"]}," header and the refresh token in the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["refresh-token"]}," header, plus ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["vbasoftware-client-id"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["vbasoftware-client-code"]},", and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["vbasoftware-database"]},", and returns the same shape as a login. The samples log in again instead, which needs nothing beyond the credentials you already have."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"password-resets","__idx":6},"children":["Password resets"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["If a user forgets their password, ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/openapi/vbasoftware/vbasoftware.api/user/forgotpassword"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["POST /forgot-password"]}]}," with the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["userID"]}," sends the user a confirmation code. ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/openapi/vbasoftware/vbasoftware.api/user/confirmforgotpassword"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["POST /confirm-forgot-password"]}]}," then sets the new password, with ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["userID"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["password"]},", and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["confirmationCode"]},". Both send ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["vbasoftware-client-id"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["vbasoftware-client-code"]},", and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["vbasoftware-database"]},". For an API service user, it is usually simpler to ask whoever issued your credentials."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"common-authentication-issues","__idx":7},"children":["Common authentication issues"]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"What you see"},"children":["What you see"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Likely cause"},"children":["Likely cause"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Fix"},"children":["Fix"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["401"]}," from ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["POST /user-authentication"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Wrong username or password, or the wrong client ID, client code, or database for that user."]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Check each value with whoever issued your credentials."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["challengeName: NEW_PASSWORD_REQUIRED"]}," instead of tokens"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["The user still has a temporary password."]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Set a permanent password with ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/openapi/vbasoftware/vbasoftware.api/user/userchangetemppassword"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["POST /change-temporary-password"]}]},", then log in again."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["401"]}," on a data call"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["The ID token is missing, expired, or not sent as ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Bearer"]},"."]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Log in again, and send ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Authorization: Bearer "]},"."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["403"]}," with ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["{\"message\":\"Forbidden\"}"]}," on every call"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["The ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["x-api-key"]}," header is missing or wrong."]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Send your API key in ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["x-api-key"]}," on every request, login included."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["429"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["More than 25 requests per second (burst 50) on your API key."]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Slow down and retry with backoff. The samples do this for you."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Login or data calls fail for a database you expect to use"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["The ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["vbasoftware-database"]}," value does not match a database your user can reach."]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Use the database name you were given, exactly as issued."]}]}]}]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"keep-credentials-safe","__idx":8},"children":["Keep credentials safe"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Load the API key, client ID, client code, username, and password from a secrets manager or environment variables, never from source code."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Keep tokens in memory. Do not write them to disk or share them between systems."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Never log passwords, tokens, the API key, or full ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Authorization"]}," headers. Log the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["debug.activityID"]}," instead."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Rotate the password and API key according to your security policy, and straight away if they may have been exposed."]}]},{"$$mdtype":"Tag","name":"Admonition","attributes":{"type":"info","name":"Contacting support"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Send VBA support:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["debug.activityID"]}," from the response"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["the date and time of the call, with time zone"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["the method and path, for example ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["POST /claim-batches"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["the full ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["error"]}," object from the response"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["the request body, with passwords, tokens, and personal data removed"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Never send your password, API key, or tokens. See ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/developer-portal/help/support"},"children":["Support and escalation"]},"."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"related","__idx":9},"children":["Related"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/developer-portal/get-started/quick-start"},"children":["Quick start"]},": log in and make a first call."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/developer-portal/get-started/credentials-and-environments"},"children":["Credentials and environments"]},": what VBA issues and how to request it."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/developer-portal/concepts/requests-and-responses"},"children":["Requests and responses"]},": headers, methods, and status codes."]}]}]},"headings":[{"value":"Authentication and tokens","id":"authentication-and-tokens","depth":1},{"value":"The flow","id":"the-flow","depth":2},{"value":"Log in","id":"log-in","depth":2},{"value":"Handle login challenges","id":"handle-login-challenges","depth":2},{"value":"Reuse the token until it expires","id":"reuse-the-token-until-it-expires","depth":2},{"value":"Refresh tokens","id":"refresh-tokens","depth":3},{"value":"Password resets","id":"password-resets","depth":2},{"value":"Common authentication issues","id":"common-authentication-issues","depth":2},{"value":"Keep credentials safe","id":"keep-credentials-safe","depth":2},{"value":"Related","id":"related","depth":2}],"frontmatter":{"title":"Authentication and tokens","description":"How a VBAPI integration logs in, handles login challenges, sends and reuses the ID token, and keeps its credentials safe.","seo":{"title":"Authentication and tokens"}},"lastModified":"2026-10-26T21:09:33.691Z","pagePropGetterError":{"message":"","name":""}},"slug":"/developer-portal/concepts/authentication","userData":{"isAuthenticated":false,"teams":["anonymous"]},"isPublic":true}