The "directory" refers to the common structures and services which support VOCUS applications.
An account is an entity that can login to a resource. Most commonly, accounts are user accounts. Special cases include service accounts (such as those used to access the API) and anonymous accounts (placeholder accounts that aren't associated with a person, but still have an identity).
User accounts can have pilot data attached to them. There are many pilot-related data points that can be configured inside FlightRisk.
A tail is an instance of a particular aircraft, that is, a tail number in an organization's fleet. Tails always belong to a domain.
A domain is a security container that usually maps 1-1 to a company/client. Domains contain accounts and tails. Domains define groups and rights; domains may have custom settings assigned to them. They are a key boundary by which data is segregated.
An enterprise domain is a special type of domain that can contain other domains. A large company may want their own enterprise so that they can have multiple child domains. A partner may wish to connect to an enterprise and replicate their customers, each customer as a child domain.
VOCUS contains multiple applications. Accounts and domains must be given access to the application(s) or users will not be able to use them.
A source provides and/or consumes data from VOCUS.
A source may be an organization, or an application provided by an organization. A source may be granted the ability to login via a service account and may then perform operations against VOCUS APIs, including actions on behalf of users.
Sources are automatically managed by VOCUS or configured by VOCUS administrators. However, it is important to understand that multiple sources may reference the same objects in VOCUS.
The source that creates an object is considered its owner. Other authorized sources may reference that object, but their ability to alter it will be minimal. This avoids conflicts between multiple sources and confusing users with data that appears to arbitrarily change.
Object ownership can be changed from VOCUS by a domain administrator.
Service accounts are lightweight accounts used solely for automated connections from a source.
A service account is not related to an individual, nor can it be used to login to the VOCUS user interface. However, it can impersonate any user account and act on any domain within its scope.
A service account is highly privileged and the credentials should be encrypted when stored.
A Mapped ID is the API caller's ID for an object. They allow the API caller to associate their ID with an object in VOCUS.
Mapped IDs must be unique and immutable. They should not be based on user input, but should be a value like a database primary key or a GUID.
Bob is a user of your application. Your internal, unique ID for Bob is 1. When you create Bob's user account using the VOCUS API, you can (and should) identify Bob by
the ID of 1. A mapping between Bob's account, your application (the source), and the ID of 1 are stored in VOCUS.
You later request a risk assessment using the FlightRisk API. This risk assessment has Bob on the crew, so his ID of 1 should be passed.
VOCUS will map this ID to Bob's VOCUS account and the risk assessment will correctly be associated with him.
A source mapping is a record within VOCUS that contains the ID of the source, the source's ID for the object (the Mapped ID), and the internal ID of the object. This is all the information needed to locate the object.
VOCUS automatically creates and reads source mappings.
When a source passes an ID in a request, the VOCUS directory is searched for source mappings. The scope of this search depends on the scope of the service account making the request. If the account was created at the enterprise-level, the scope is the enterprise and all its descendents. If the account was created in a non-enterprise domain, the scope is limited to that domain.
Multiple sources may wish to reference the same objects such as users and tails. However the sources likely don't know about each other, and there is a risk of duplication. This problem can be solved by manually adding/moving mappings within the VOCUS UI.
However, VOCUS will also attempt to match certain types of objects based on their data. For example, if Source B tries to create a tail that Source A has already created, VOCUS will match the tail number and add a new mapping for Source B to the existing tail rather than creating a duplicate item.
A domain or user account is given access ("joined") to an application via the API or the UI. Access may be removed ("disjoined") from an application.
The directory provides a hierarchical group structure that consists of built-in groups and ad hoc user-defined groups. Groups may be assigned rights, which grant the ability to perform certain actions and/or access functional areas.
Domain administrators are granted a large number of rights by default. If their domain is an enterprise, they will automatically have rights within the subdomain that correspond to the subdomain's Domain Administrators group.
The API does not provide support for group membership or management. This is primarily because VOCUS apps offer fine-grained permissions which will likely not be known or easily-managed by an external caller. Full group management functionality is available via the UI and VOCUS administrators have access to training that teaches them how to model the organization to meet their needs.
API Version 14.1.9203.25249
Copyright ©2008-2025 Polaris Aero, LLC.