Account Administration API - Developer Guide

1. Overview & Introduction

The Account Administration API exposes read access to the organizational records that govern how your integration interacts with other Vitu API products. It answers three operational questions: which locations exist, which users exist, and what each user is permitted to do at each location.

The domain model is built from three core nouns:

• Location — a physical or organizational site (with address details) against which fees and transaction requests are made. Locations are the anchor for access control.
• User — an individual record that can be associated with fees and transaction requests.
• Access — the mapping that ties a user to the locations they can act on, and the specific operations permitted at each location.

The relationship is hierarchical in practice: a user's access is expressed per location, and each location grants a set of operation codes. A user has no meaningful capability until access records associate them with one or more locations.

The API is versioned and environment-scoped. The spec defines a single server template with an env variable covering production (api), staging (api-stage), and test (api-test). Treat these as fully separate deployments — credentials, data, and identifiers do not carry across environments. Refer to the spec's servers block for the exact URL structure.

Sensitive-data note: User records include personal identifiers such as names and email addresses. Handle responses accordingly and restrict logging/storage of these fields.

2. Getting Started / First Call

Prerequisites

• A registered Vitu integration with issued OAuth 2.0 client credentials.
• The ability to request and attach a bearer token (see §3).
• A target environment (api, api-stage, or api-test).

Obtain access

Credentials are issued by Vitu and can be obtained from the Key Management area within Vitu's Developer Portal.

Minimal happy path

1. Request an access token from the token endpoint using the client-credentials grant (see the oneVituOauth scheme in the spec for the formal definition and the token URL).
2. Call the GetLocations operation to confirm connectivity and discover available locations.
3. Call GetUsers to retrieve user records.
4. Call GetAccessList to see which operations each user holds per location.

A successful token request followed by a 200 from GetLocations confirms your integration is wired correctly. Consult the spec for the exact response shape of each operation.

3. Authentication & Access Walkthrough

Authentication uses the oneVituOauth scheme — OAuth 2.0 client-credentials grant. The spec holds the formal definition (grant type, token URL, and the oneapi:access scope). This section covers only the operational mechanics.

Only one scheme exists. There is no API-key or authorization-code alternative. If you expected user-delegated auth, note the x-on-behalf-user-id header on the access operation (below), which is the mechanism for acting in the context of a specific user.

Obtaining a token

1. Retrieve client credentials from the Key Management area of Vitu's Developer Portal.
2. Exchange them at the token endpoint defined by oneVituOauth for a bearer token, requesting the oneapi:access scope.

Attaching the token

Send the token as a bearer credential on every request. All operations require the oneVituOauth scheme with oneapi:access.

Token lifecycle

• Tokens expire. Cache a token and reuse it until near expiry, then request a new one.
• There is no refresh-token flow in client-credentials — re-request a token using your credentials.
• On an authentication failure response, obtain a fresh token and retry once; if it recurs, treat it as a credential/permission problem rather than retrying blindly (see §Error handling).

On-behalf-of context

The access operation accepts an optional x-on-behalf-user-id header to scope the response to a particular user. See the spec for the exact header definition.

4. Key Concepts & Glossary

Relationships & dependencies

• User → Access → Location. A user's capabilities are meaningless without access records linking them to locations. Access is always expressed per location, and each location carries its own list of operation codes.
• Location and User records are independent lists; Access is the join between them.
• There are no lifecycle states exposed in this version — records are read-only and carry no status field.

5. Common Use Cases & Integration Patterns

All operations are read-only, so these patterns are about discovery and reconciliation, not mutation.

Use case A - Discover available locations

Goal: enumerate the locations your integration can transact against.

1. GetLocations — retrieve the location list, paging through results (see §Pagination).

Use this to populate location pickers or validate a location id before submitting requests to other Vitu products.

Use case B - Enumerate users

Goal: obtain the user records available for fees/transaction requests.

1. GetUsers — retrieve the user list, paging as needed.

Use case C - Determine what a user can do

Goal: resolve a user's permitted operations per location before initiating a workflow in another product.

1. GetUsers — identify the user id of interest.
2. GetAccessList — retrieve access records; optionally scope to a single user with the x-on-behalf-user-id header.
3. Cross-reference each returned location id against GetLocations output for human-readable location context.

Recommended pattern: This is a synchronous, poll-on-demand model. There are no webhooks or async operations. Cache location and user lists and refresh them on a schedule appropriate to how often your organization's records change; re-fetch access before an action if authorization must be current.

6. Behavioral & Operational Notes

• Read-only: No operation in this version mutates state. All are safe to retry (subject to rate limits).
• Result caps: Each list response is capped (the spec's array maxItems). This is a schema ceiling, not a substitute for paging — use the paging parameters to traverse full result sets.
• No ordering guarantee: The spec does not define a sort order for any list. Do not assume stable ordering across calls; sort client-side if you need determinism.
• Access is a snapshot: A user's access reflects the state at query time. Because there are no change events, re-query when currency matters.

7. Environments & Sandbox Access

Three environments are exposed via the server template's env variable: production (api), staging (api-stage), and test (api-test). They are isolated — data and identifiers are not shared. Use api-test for development and integration, api-stage for pre-production validation, and api for live traffic. Access to each is governed by the credentials issued for it (see §3). Refer to the spec for exact URLs.

8. Rate Limiting & Quotas

The API enforces rate limits: exceeding them returns the spec's too-many-requests response. On that response, back off and retry after the limit window resets. The spec does not document specific limit values or dedicated limit headers, so do not assume a Retry-After or quota header is present — treat the rate-limit response class itself as your signal and apply exponential backoff (see §Error handling).

9. Pagination Conventions

List operations use offset-based paging via the shared limit (page size) and offset (items to skip) parameters; see the spec for their bounds and defaults. Iterate by advancing the offset until a page returns fewer items than the requested limit.

As noted in §6, GetUsers additionally exposes page/size. Prefer the limit/offset convention for consistency across operations, and send only one scheme per request.

10. Error Handling & Troubleshooting

All error responses share the spec's error collection schema (a list of messages). Handle errors by class, not by memorizing codes — the spec is the source of truth for which status maps to which condition.

Backoff convention: For retryable classes, use exponential backoff with jitter (e.g., increasing delays across a small number of attempts) and a stop condition (max attempts or max elapsed time). Never retry validation or forbidden errors.

11. Data Sensitivity & Compliance Notes

User records expose personal identifiers (names, email addresses). Minimize retention, avoid logging these fields in plaintext, and restrict access to systems that need them. No regulated-data classification (e.g., PII handling requirements) is specified in the spec; confirm applicable obligations with the API owner. This is guidance, not legal advice.

12. Support & Resources

For any API assistance, contact Vitu's API support team at [email protected].