This page is for whoever sets up a VBAPI integration at a client organization. It explains each credential VBA issues and which header it goes in, which host and database you call, and how to keep the credentials safe.
VBA issues six values. All of them come from VBA; you do not create them yourself.
| Credential | What it is | Where it goes |
|---|---|---|
| API key | Identifies your integration to the API. Rate limits (25 requests per second sustained, 50 burst) apply per API key. | x-api-key header on every call |
| Client ID | Part of your organization's login configuration. | vbasoftware-client-id header when you log in |
| Client code | Part of your organization's login configuration. | vbasoftware-client-code header when you log in |
| Database name | The VBASoftware database a call reads from or writes to. | vbasoftware-database header on every call, including login |
| Username | The VBASoftware user your integration logs in as. | Basic authentication on POST /user-authentication |
| Password | That user's password. A new user may first have to replace a temporary password; see the Quick start. | Basic authentication on POST /user-authentication |
Logging in with POST /user-authentication returns an ID token, which every other call sends as Authorization: Bearer <idToken>. Authentication and tokens explains token lifetime and renewal.
Contact your VBA Account Executive to request an API key and the other values. Support and escalation lists the other ways to reach VBA.
Clients use one host, the production API:
https://vbapi.vbasoftware.com/vbasoftwareThere is no separate client sandbox host. You choose the database on every request with the vbasoftware-database header, so the database name you were given decides whose data a call reads or changes.
Because every call reaches production, write calls (POST, PUT, DELETE) change real records. Ask VBA whether a non-production database is available for your organization to build and test against. If it is, you call it on the same host by sending its name in vbasoftware-database.
- Keep the API key, password, and tokens out of source code and version control. Load them from environment variables or a secrets manager.
- Never log or display tokens, passwords, or API keys. Mask them in error reports.
- Keep tokens in memory, not on disk, and discard them when your process ends.
- Never send credentials or tokens to VBA support. The
debug.activityIDfrom a response is enough to find a request. - If a credential may have been exposed, contact VBA to have it replaced.
- Quick start: use your credentials to make a first call.
- Try it in the browser: call operations from the API reference.