Types

This document describes the types used by the Groove.id API.

APIKey

APIKey represents a static bearer token. In the API the key is identified by the string gv followed by 8 random lower-case characters from the base32 alphabet.

The tokenized form of the key is the string “gv” followed by the 8 random characters (the key ID), followed by the tenant ID and then another 32 random base32 lower case characters (the secret). (20 bytes of entropy)

This allows the key to be identified by it’s prefix, the first 10 characters and allows the key to identify the tenant.

An example tokenized string:

+-- kind
| +-- key id
| |       +-- tenant
| |       |             +-- secret
| |       |             |
v v       v             v
gvfoniuykysuayxvog0oevdnrzuynhmi5fqz2keanptobyjhnvycedjn

Name (string) - A descriptive name for the key.
Tags (Tags) - A list of user-defined tags for this object
Owner (string) - The ID of the user that created the key, or an empty string if the API key does not represent any user.
Scopes (Array of string) - The authorization scopes that the API key is authorized for.
LastUsed (RFC3339-formatted timestamp) - When the key was last successfully used to make a request.

AWSApp

AWSApp represents a AWS app integration

RoleARN (string) - The ARN of the cross-account role we use to sign in
SAMLProviderARN (string) - The ARN of the Groove.id SAML provider, if SSO is enabled.
StackName (string) - The name of the CloudFormation stack we used to set up access.
Policies (Array of string) - A list of available iam.Policy ARNs.
Groups (Array of string) - A list of available group names.

AbacusApp

AbacusApp represents the Abacus-specific data for an app

ExpenseTags (base64-encoded binary) - JSON-encoded []abacus.ExpenseTagSchema

Account

Account represents a user’s account in an app.

Account object IDs must be the of the form AppID + “-” + UserID. When creating an Account object you must specify the AppID, the UserID and the object ID as specified. Once set, the AppID and UserID and ID properties are immutable.

Beta Caution: Account objects are considered “beta” and so the fields listed here may be removed or changed without incrementing the version number of the API.

Tags (Tags) - A list of user-defined tags for this object
AppID (string) - The application this account refers to.
UserID (string) - The user this account refers to.
Identifier (string) - The identifier of this account from the application’s point of view.
State (ChangeAccountState) - The current state of this account.
Licenses (Array of AppLicense) - The licenses assigned to the account.
Roles (AppRoles) - The roles assigned to the account.
Username (string) - The username of the user in this account. This username has meaning in the upstream application only.
Name (Name) - The name of the user in this account.
EmailAddress (string) - The email address of the user in this account.
HavePassword (bool) - True if the account has an initial password that can be delivered to the user.
Groups (Array of AppGroup) - If the application has the context of groups, a list of the group identifiers this user is a member of. (Note: these items have meaning in the application, they are not Groove.id groups)
Properties (AccountProperties)
ProcessingAccountChange (string) - ID of the AccountChange currently being processed for this account.

AccountChange

AccountChange represents the application of a change to an Account.

Beta Caution: Account and related types are considered “beta” and so the fields listed here may be removed or changed without incrementing the version number of the API.

Tags (Tags) - A list of user-defined tags for this object
AccountID (string) - The account ID (Account.Metadata.ID) to be changed. Must be populated.
IfMatch (string) - The current Etag of the account to be changed (nb. not of this AccountChange). Must be populated, unless the Change represents an account creation.
Creator (string) - The user ID of the user that created the request
SetState (ChangeAccountState) - New state for the account to be in.
AddLicenses (Array of AppLicense) - New licenses to be assigned to the account.
RemoveLicenses (Array of AppLicense) - Licenses to be removed from account.
AddRoles (Array of AppRole) - Roles to assign to the account.
RemoveRoles (Array of AppRole) - Roles to remove from the account.
SetUsername (string) - New username for the account.
AddGroups (Array of AppGroup) - Groups to which to add the account.
RemoveGroups (Array of AppGroup) - Groups from which to remove the account.
SetProperties (Array of AccountProperty) - Extended properties to set
ClearProperties (Array of AccountProperty) - Extended properties to clear.
DeliverPassword (DeliverPassword) - Records having delivered a password
MigrateTo (string)
Result (AccountChangeResult) - The result of this account change application. Will be populated/updated by the server.
ApplyAfter (string) - The ID of the AccountChange which should be processed before this one (if any). If set, IfMatch must be empty.
MigrateTaskResults (base64-encoded binary)
WorkflowAssignees (Array of string) - For workflow changes, a list of the users IDs assigned to complete the task.
WorkflowTicketNumber (int) - For workflow changes, the unique ticket number of the request.
WorkflowNextReminder (RFC3339-formatted timestamp) - For workflow changes, the time that the next reminder should be sent.
WorkflowPreviousAccountState (ChangeAccountState) - For workflow changes, the state of the Account before the change.
WorkflowLog (Array of WorkflowLogEntry) - For workflow changes, the history of changes made to the task

AccountChangeResult

AccountChangeResult represents the current status of an AccountChange operation. StatusCode will change from 0 to 102 when Groove.id begins to process the AccountChange operation.

Beta Caution: Account and related types are considered “beta” and so the fields listed here may be removed or changed without incrementing the version number of the API.

StatusCode (int) - 102 (Processing), 200 (OK), 409 (Conflict), 500 (Internal Server Error)
Status (string) - English-language string detailing a 409 or 500 status.
Assignee (string) - the user id of the person that completed the request, if any.

AccountID

AccountID represents the identifier of an Account.

It consists of the app id, a dash, and the user id.

AppID (string)
UserID (string)

AccountProperties

AccountProperties is a list of account properties

An array of AccountProperty

AccountProperty

AccountProperty represents an extended property of an account.

Name (string) - the name of the property
Value (string) - the value of the property
DisplayName (string) - a human-friendly way to describe the name
DisplayValue (string) - a human-friendly way to describe the value (e.g., if Value is a user ID then the DisplayValue is the person’s name)

AccountState

AccountState indicates the state of a user’s account in an application

A string enumeration. Possible values are:

`` - an AccountState of type unknown
active - an AccountState of type active
suspended - an AccountState of type suspended
absent - an AccountState of type absent
create_pending - an AccountState of type create_pending

ActivationCode

ActivationCode is a code that is used to activate an account.

Tags (Tags) - A list of user-defined tags for this object
User (string) - The user ID of the user to activate. If not specified, the activation code can be used for any user.
UsesRemaining (int) - The remaining number of times the code may be used. Immutable.
UsesAllowed (int) - The number of times the code may be used.
NotBefore (RFC3339-formatted timestamp) - A time before which the code may not be used.
NotAfter (RFC3339-formatted timestamp) - A time after which the code may not be used.
Active (bool) - If true then the code is valid, otherwise the code cannot be used.

Address

Address represents a user’s physical address

Country (string) - Country.
CountryCode (string) - The country code. Uses the ISO 3166-1 standard.
CustomType (string) - If the address type is custom, this property contains the custom value.
ExtendedAddress (string) - For extended addresses, such as an address that includes a sub-region.
Formatted (string) - A full and unstructured postal address. This is not synced with the structured address fields.
Locality (string) - The town or city of the address.
POBox (string) - The post office box, if present.
PostalCode (string) - The ZIP or postal code, if applicable.
Primary (bool) - If this is the user’s primary address. The addresses list may contain only one primary address.
Region (string) - The abbreviated province or state.
SourceIsStructured (bool) - Indicates if the user-supplied address was formatted. Formatted addresses are not currently supported.
StreetAddress (string) - The street address, such as 1600 Amphitheatre Parkway. Whitespace within the string is ignored; however, newlines are significant.
Type (AddressType) - The address type. Acceptable values are: “custom” “home” “other” “work”

AddressType

AddressType indicates the type of an Address

A string enumeration. Possible values are:

custom - an Address of type custom
home - an Address of type home
other - an Address of type other
work - an Address of type work

AdobeCCApp

AdobeCCApp represents the Adobe-specific data for an App.

Certificate (base64-encoded binary) - DER encoded public key
ClientID (string)
ClientSecret (Secret)
TechnicalAccountID (string)
TechnicalAccountEmail (string)

App

App represents an application or connection in Groove.id.

An application can be a SAML service provider, a credential escrow provider, or another custom implementation.

Name (string) - The display name of the application.
Tags (Tags) - A list of user-defined tags for this object
Owners (Array of string) - The ID of the users that can administer the application. Global admins can also administer the application.
MetadataXML (base64-encoded binary) - If the application is a SAML application and uses static XML metadata (some providers do, many don’t) then this is the service provider metadata for this application.
MetadataURL (string)
MetadataLastFetched (RFC3339-formatted timestamp)
MetadataLastEtag (string)
Icon (Icon) - A visual indicator of the application, usually a logo.
HideFromDashboard (bool) - True if the app should be hidden from the app dashboard
Provider (string) - The name of the provider that handles this application. This value must correspond to one of the official providers.
Provisioned (bool) - True if the application has been set up and sign-ins can proceed, false if it still needs to be set up.
Slack (SlackApp) - Provider specific data if Provider is slack.
Google (GoogleApp) - Provider specific data if Provider is google.
AWS (AWSApp) - Provider specific data if Provider is aws.
O365 (O365App) - Provider specific data if Provider is o365.
Salesforce (SalesforceApp) - Provider specific data if Provider is salesforce.
Greenhouse (GreenhouseApp) - Provider specific data if Provider is greenhouse.
Cloudflare (CloudflareApp) - Provider specific data if Provider is cloudflare.
Radius (RadiusApp) - Provider specific data if Provider is radius.
LDAP (LDAPApp) - Provider specific data if Provider is ldap.
Abacus (AbacusApp) - Provider specific data if Provider is abacus.
Docusign (DocusignApp) - Provider specific data if Provider is docusign.
AdobeCC (AdobeCCApp) - Provider specific data if Provider is adobecc.
Webex (WebexApp) - Provider specific data if Provider is webex.
Pingboard (PingboardApp) - Provider specific data if Provider is pingboard.
Workflow (WorkflowApp) - Provider specific data if Provider is pingboard.
HighValue (bool) - If true then signing in to this application requires a medium integrity. If false, signing in requires low integrity (the default).
URL (string) - The URL to the application. Some applications need this to redirect a signed in user, or to kick off the sign-in process. It’s meaning is provider specific.
SetupToken (string) - A short-lived secret used when setting up a new app service (such as a synchronization daemon). The daemon presents the setup token on it’s first run and exchanges it for an entry in ServiceAccounts.
SetupShortLinkID (string) - If the SetupToken is associated with a short link, this is the ID of that short link.
ServiceAccounts (Array of AppServiceAccount) - Service accounts are devices used to authorize a daemon or service that facilitates the functioning of the app.
Groups (Array of string) - A list of groups that grant access to this app. The user must be an active member of at least one of the listed groups to sign in.
AppGroups (Array of AppGroup) - A list of the available groups in the application
AppRoles (Array of AppRole) - A list of the available roles in the application
AppLicenses (Array of AppLicense) - A list of the available licenses in the application
EnableImpersonation (bool) - True if prompts to impersonate other users should be shown. Even if this is true, a user still needs to be authorized to impersonate another user.
CreateValidUsersFromAccounts (bool) - If true then when we encounter an app account that doesn’t correspond to a Groove.id user, we will create a valid User object for it. If false, then the User is still created, but it is marked as deleted.
Username (string) - For static credential delivery applications, the user name to enter.
PasswordLastChanged (RFC3339-formatted timestamp) - When the password was last changed.
BrowserMFAPrompt (bool)
BrowserMFAAnswer (Secret)
OAuth2TokenType (string) - For apps that require a service token (e.g. to enable just-in-time provisioning), this is the OAuth2 token type
OAuth2RelyingParty (bool) - If true then we will delegate authentication to this app via OAuth2.
OAuth2RelyingPartyHighSecurity (bool) - If true then the OAuth 2.0 app performs strong authentication, e.g. with multi-factor.
OAuth2Scope (string) - the scope associate with the OAuth 2.0 token
SigninMode (string) - Some providers can be used in different ways. This provider-specific field indicates the way the signin will happen. Common values include saml and credential_escrow.
AssertionConsumerServiceURL (string)
AssertionConsumerServiceBinding (AssertionConsumerServiceBinding)
NameIDKind (UserIdentityKind)
NameIDFormat (string)
CustomAttributes (Array of AppCustomAttribute)
CustomerID (string) - The identifier for the tenant, if this is a multi tenant app.
CustomerDomain (string) - The domain name associated with the app.
AllCustomerDomains (Array of string) - All domains & domain aliases associated with the app.
DeliverPasswordAnonymous (bool) - When delivering passwords for new accounts, embed the authorization code in the link, rather than requiring them to sign in to receive it.
LastImportStarted (RFC3339-formatted timestamp)
LastImportFinished (RFC3339-formatted timestamp)
LastImportError (string)
API (AppAPI)

AppAPI

AppAPI describes the status of the API connection to the app

StatusCode (int)
Status (string)
CheckStart (RFC3339-formatted timestamp)
CheckEnd (RFC3339-formatted timestamp)

AppCustomAttribute

AppCustomAttribute represents custom attributes added to the SAML assertion.

Name (string)
FriendlyName (string)
Kind (UserIdentityKind)

AppGroup

AppGroup represents a group in an application

ID (string)
Name (string)

AppLicense

AppLicense represents a license in an application

ID (string)
Name (string)

AppRole

AppRole represents a role in an application

ID (string)
Name (string)

AppRoles

AppRoles is a list of AppRole

An array of AppRole

AppServiceAccount

AppServiceAccount represents devices attached to an app that perform special tasks, such as synchronization.

If SetupSecret is non-empty, then this is a prototype service account. The first time a device contacts Groove.id with the given SetupSecret, it will be converted into an actual service account by removing SetupSecret and setting DeviceID.

Only permanent AppServiceAccounts can be used to authenticate a service. Prototype AppServiceAccount objects can only be swapped for permanent AppServiceAccount objects. Exactly how this happens is app provider specific.

Created (RFC3339-formatted timestamp) - When the service account was created
SetupSecret (string) - The initial secret, used once during setup.
SetupExpires (RFC3339-formatted timestamp) - When the initial secret expires.
DeviceID (string) - Once provisioned the ID of the associated device.
Scopes (string) - The list of scopes authorized for the device.

AssertionConsumerServiceBinding

AssertionConsumerServiceBinding represents the SAML binding for an ACS URL

A string enumeration. Possible values are:

urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect - the SAML HTTP redirect binding.
urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST - the SAML HTTP POST binding.

AuthResponse

AuthResponse indicates the current state of an authorization session. It is returned by the /ap1/v1/auth/* handlers.

OK (bool) - true if there is sufficient authentication for the intent to proceed
Activate (FactorState) - true if the user is active
Email (FactorState) - Tells if the user can, must, or has provided a PIN.
PIN (FactorState) - Tells if the user can, must, or has provided a PIN.
Mobile (FactorState) - Tells if the user can, must, or has provided a mobile push.
TOTP (FactorState) - Tells if the user can, must, or has provided a TOTP code.
U2F (FactorState) - Tells if the user can, must, or has provided a U2F token.
OTP (FactorState) - Tells if the user can, must, or has provided an OTP code via email.
Video (FactorState) - Tells if the user can, must, or has provided a video vouch.
Backup (FactorState) - Tells if the user can, must, or has provide a backup code.
ActivationCode (FactorState) - Tells if the user can, must, or has provided an activation code.
Password (FactorState) - Tells if the user can, must, or has provided a password.
PSTN (Array of PSTNFactorState) - The available PSTN devices (for SMS or voice authentication)
OAuth2 (OAuth2FactorStates)

BackupCode

BackupCode represents a backup code that can be used to sign in once.

Prefix (string)
Created (RFC3339-formatted timestamp)

BackupCodes

BackupCodes is a list of backup codes

An array of BackupCode

BrowserCookie

BrowserCookie represents a single browser cookie.

Name (string) - the cookie’s name.
Value (string) - the cookie’s value.
Domain (string) - the cookie’s domain.
Path (string) - the cookie’s path.
Expires (float64) - the cookie’s expiration date as the number of seconds since the UNIX epoch.
Size (int) - the cookie’s size.
HTTPOnly (bool) - True if cookie is http-only.
Secure (bool) - True if cookie is secure.
Session (bool) - True in case of session cookie.
SameSite (string) - the cookie’s SameSite type.

BrowserError

BrowserError is an error returned from headless browser operations that includes a screenshot and dump of the DOM.

Err (error) - A description of the error that occurred
URL (string) - The URL that was active when the error occurred
HTML (string) - The HTML contents of the DOM.
Screenshot (base64-encoded binary) - A screenshot of the page, in PNG format.

BrowserLocation

BrowserLocation represents an HTML5 browser location state

pathname (string)
search (string)
state (&{X:json Sel:RawMessage})
hash (string)
key (string)

BrowserState

BrowserState represents the state of a browser. It is passed between the headless browser on the server and the Chrome extension which can apply it the user’s browser.

URL (string)
Cookies (Array of BrowserCookie)

ChangeAccountState

ChangeAccountState describes the intended state of an Account

Beta Caution: Account and related types are considered “beta” and so the fields listed here may be removed or changed without incrementing the version number of the API.

A string enumeration. Possible values are:

`` - a ChangeAccountState of type unknown/missing
invited - a ChangeAccountState of type invited
enabled - a ChangeAccountState of type enabled
disabled - a ChangeAccountState of type disabled
deleted - a ChangeAccountState of type deleted

CloudflareApp

CloudflareApp represents Cloudflare specific data for redirect when logging in to your specific domain

AppName (string)
AssertionConsumerURL (string)

DeliverPassword

DeliverPassword describes having delivered a password link to a user.

EmailAddress (string)
PhoneNumber (string)

DeliveredCredential

DeliveredCredential represents credentials for an account.

Provider (string) - The name of the app provider, e.g. ‘o365’.
URL (string) - The signin URL.
Username (string) - The user name.
Password (string) - The password.

Device

Device describes a device that a user has used to sign in. It is not a full-fledged object, but rather has properties derived from AuthState.

SignedBoostIntent (string) - This may contain a value that can be used as the body of a request to /api/v1/auth/boost that will automatically sign in the most recent session on this device.
Location (LocationInfo) - information about the proported physical location of the other session.
Network (NetworkInfo) - information about the network attachment of the other session.
HostInfo (HostInfo) - information about the other host.

DocusignAccount

DocusignAccount contains the ID & name of a Docusign Account

ID (string)
Name (string)
BaseURI (string) - Docusign API base URIs are on a per-Account basis: https://developers.docusign.com/esign-rest-api/guides/authentication/user-info-endpoints#form-your-base-path
OrganizationID (string)

DocusignApp

DocusignApp represents the Docusign-specific data for an App.

A large Docusign Organization may have several Accounts. In Groove.id, we represent each Account as a single App; Groove.id admins may add multiple Docusign Apps to manage multiple Docusign Accounts. See: https://developers.docusign.com/orgadmin-api/guides

Account (DocusignAccount) - The Docusign Account this App represents. Once set, this should never be changed.
DiscoveredAccounts (Array of DocusignAccount) - Docusign Accounts we discovered when this app was first authorized via OAuth.

DomainGuess

DomainGuess represents the guess of summary information for a domain

Title (string)
Image (base64-encoded binary)
VirtualHost (string)

Donation

Donation represents an integrity donation from one device to another for the same user.

Tags (Tags) - A list of user-defined tags for this object
State (DonationState)
IntegrityLevel (IntegrityLevel)

DonationState

DonationState represents the state of the donation

A string enumeration. Possible values are:

new - the donation is newly created.
accepted - the donation is waiting for the strong device to accept it.
valid - the donation is complete.
failed - the donation has failed due to an internal error.
expired - the donation has expired.
blocked - the donation has been blocked by other donations that were
cancelled - the donation has been abandoned by the user.

Email

Email represents an email address

Address (string) - The user’s email address. Also serves as the email ID. This value can be the user’s primary email address or an alias.
CustomType (string) - If the value of type is custom, this property contains the custom type string.
Primary (bool) - Indicates if this is the user’s primary email. Only one entry can be marked as primary.
Type (EmailType) - The type of the email account. Acceptable values are: “custom”, “home”, “other”, “work”, }

EmailType

EmailType represents the type of an Email

A string enumeration. Possible values are:

custom - an Email of type custom
home - an Email of type home
other - an Email of type other
work - an Email of type work

EnrollBackupCodeState

EnrollBackupCodeState represents the enrollment state of a Backup code.

This, among the other *EnrollState structure may seem repetitive, but they are placeholders for a future time when we have more factor-specific information to include.

Prefix (string)
Created (RFC3339-formatted timestamp)

EnrollMobileDeviceState

EnrollMobileDeviceState represents the enrollment state of a MobileDevice.

This, among the other *EnrollState structure may seem repetitive, but they are placeholders for a future time when we have more factor-specific information to include.

LastUsed (RFC3339-formatted timestamp)
Created (RFC3339-formatted timestamp)
DeviceName (string)
UserAgent (string)
DeviceSystemName (string)
DeviceSystemVersion (string)
DeviceModel (string)

EnrollPINState

EnrollPINState represents the enrollment state of a PIN.

This, among the other *EnrollState structure may seem repetitive, but they are placeholders for a future time when we have more factor-specific information to include.

LastUsed (RFC3339-formatted timestamp)
Created (RFC3339-formatted timestamp)

EnrollPasswordState

EnrollPasswordState represents the enrollment state of a Backup code.

This, among the other *EnrollState structure may seem repetitive, but they are placeholders for a future time when we have more factor-specific information to include.

Created (RFC3339-formatted timestamp)
Updated (RFC3339-formatted timestamp)
AppID (string)

EnrollState

EnrollState represents the enrollment state of the current user. It is returned by the GET /api/v1/enroll endpoint.

PIN (EnrollPINState)
TOTP (EnrollTOTPState)
MobileDevices (&{Map:181854 Key:string Value:EnrollMobileDeviceState})
U2FDevices (&{Map:181945 Key:string Value:EnrollU2FDeviceState})
Video (EnrollVideoState)
PSTN (Array of PSTNDevice)
BackupCodes (Array of EnrollBackupCodeState)
Passwords (&{Map:182309 Key:string Value:EnrollPasswordState})
OAuth2 (&{Map:182400 Key:string Value:OAuth2FactorState})

EnrollTOTPState

EnrollTOTPState represents the enrollment state of a TOTP.

This, among the other *EnrollState structure may seem repetitive, but they are placeholders for a future time when we have more factor-specific information to include.

LastUsed (RFC3339-formatted timestamp)
Created (RFC3339-formatted timestamp)

EnrollU2FDeviceState

EnrollU2FDeviceState represents the enrollment state of a U2FDevice.

This, among the other *EnrollState structure may seem repetitive, but they are placeholders for a future time when we have more factor-specific information to include.

LastUsed (RFC3339-formatted timestamp)
Created (RFC3339-formatted timestamp)
RegisteredOrigin (string)

EnrollVideoState

EnrollVideoState represents the enrollment state of a Video.

This, among the other *EnrollState structure may seem repetitive, but they are placeholders for a future time when we have more factor-specific information to include.

LastUsed (RFC3339-formatted timestamp)
Created (RFC3339-formatted timestamp)

ErrClockSkew

ErrClockSkew is returned we cannot validate the gv1 auth because the date skews by too much.

Client (RFC3339-formatted timestamp)
Server (RFC3339-formatted timestamp)
Max (an RFC3339-formatted duration)

ErrorCode

ErrorCode represents a machine-readable error we return from a request

A string enumeration. Possible values are:

Clock Skew
Invalid Session
Reason Required
Group Membership
Browser Error
Account Pending
Session Required
Insufficient Integrity
Already Completed
Expired
Vouch Request Already Accepted
Vouch Request Already Rejected
Vouch Request Already In Progress
Vouch Request Canceled
Vouch Request Expired
Request Expired
Duplicate Email
Duplicate Login
Account Missing
Account Inactive
Account Suspended
Incorrect TOTP code
Incorrect PSTN verification code
Impersonate Account Inactive
Device Unregistered
Email Already Provided
Incorrect Password
Account Deleted
User Required
Payment Required

EventStreamFilter

EventStreamFilter expresses a filter for websockets

Field (string)
Operator (string) - <, <=, =, >=, or >
Value (&{X:json Sel:RawMessage})

EventStreamRequest

EventStreamRequest is the type of each frame sent to the /events websocket endpoint.

Channel (string)
Kind (string) - The kind of events to stream, e.g. “User” or “Tenant”
ID (string) - To monitor events for a specific object, this is the object ID. If omitted then all events of the Kind are monitored.
Filter (Array of EventStreamFilter) - A list of filters to limit the objects returned.
Intent (string)

ExternalID

ExternalID is an external ID for the user, such as an employee or network ID.

CustomType (string) - If the external ID type is custom, this property holds the custom type.
Type (ExternalIDType) - The type of the ID. Acceptable values are: “account”, “custom”, “customer”, “login_id”, “network”, “organization”,
Value (string) - The value of the ID.

ExternalIDType

ExternalIDType represents the type of an ExternalID

A string enumeration. Possible values are:

account - an ExternalID of type account
custom - an ExternalID of type custom
customer - an ExternalID of type customer
login_id - an ExternalID of type login_id
network - an ExternalID of type network
organization - an ExternalID of type organization

ExternalIDs

ExternalIDs is a list of ExternalID

An array of ExternalID

FactorState

FactorState represents availability or completion of an authentication factor

CanSupply (bool) - True if the user can supply this factor.
HaveSupplied (bool) - True if the user has already supplied this factor.
MustSupply (bool) - True if the user must supply this factor for authentication to proceed.
WaitingForUser (bool) - True if the authentication factor is waiting for user input on another device, such as when waiting for the user to acknowledge a mobile push notification.
Backoff (time.Time) - If the authentication factor is temporarily disabled, this is the time when is may be re-enabled.

FeatureFlag

FeatureFlag represents an optional feature for a tenant or user.

A string enumeration. Possible values are:

lifecycle-only - to show UI for account lifecycle only, and not SSO.
aspirational-apps - to show apps that we haven’t built yet, for demo
unattended-signin - to show the unattended signin switches in the UI
show-metrics - to show metrics sidebar option in the UI
send-virtualhost-health-alerts - enables sending transactional emails for virtualhost health issues (e.g.
show-groups-list - enables the group list item in the setup sidebar nav
show-approvals - enables the approvals view in the setup sidebar nav
show-passwords - enables password management for the front end
enable-voice - enables voice calls
require-extension-to-impersonate - enables a prompt that requires the extension be installed to impersonate
always-use-canonical-virtual-host - this tenant’s requests will always be redirected to the
disable-variable-friction - means that authorization function will use a simplified model that does not
enable-billing - is set when we should show the billing tab
show-non-editable-aliases - is set when we should show the billing tab

FeatureFlags

FeatureFlags is a list of FeatureFlag

An array of FeatureFlag

GoogleApp

GoogleApp represents a Google app integration

ServerCertificate (base64-encoded binary)
DirectoryWatchChannelID (string)
DirectoryWatchChannelResourceID (string)
Groups (Array of GoogleGroup)
OrganizationalUnits (Array of GoogleOrganizationalUnit)
DisableSuspendedUserArchiveGroups (bool)

GoogleGroup

GoogleGroup represents an available Google user group.

ID (string)
Name (string)
Email (string)
Description (string)

GoogleOrganizationalUnit

GoogleOrganizationalUnit represents a G Suite organizational unit.

OrganizationalUnitID (string) - Organizational unit ID
Name (string) - Organizational unit name, eg. “sales”
Description (string) - Organizational unit description, eg. “The corporate sales team”
OrganizationalUnitPath (string) - Full path of this organizational unit, eg. “/corp/sales”
ParentOrganizationalUnitID (string) - Parent organizational unit ID
ParentOrganizationalUnitPath (string) - Path of this organizational unit’s parent, eg. “/corp”

GreenhouseApp

GreenhouseApp represents the Greenhouse specific data we must track for an app.

OnBehalfOfID (int) - The Greenhouse user ID of the first site_admin we find when we instantiate the app

Group

Group represents an access control group.

Metadata (Metadata)
Tags (Tags) - A list of user-defined tags for this object
Name (string) - The name of the group, but following e.g. DNS naming rules so that it can be translated into Windows and POSIX groups.
Description (string) - A human readable description of the group
Icon (Icon) - An icon that represents the group
Owners (Array of string) - The owner of the group
DelegateProvider (string) - DelegateProvider is the name of a plugin that provides services for this group.
DelegateID (string) - DelegateID is an opaque value managed by the delegation provider.
JoinApprovalPolicy (JoinApprovalPolicy) - one of “open”, “member approve”, “owner approve”
JoinRequiresReason (bool) - if true, then a reason must be provided to join a group
JoinRequiresHighIntegrity (bool) - if true, then high integrity is required to join, otherwise medium integrity is required
InactiveAfterInHours (int) - a membership is automatically made inactive if the membership remains unused for this number of hours.
ApprovalExpiresInHours (int) - a membership is revoked if the approval is older than this value.
ActivateNotifies (string) - Where to send notification messages, one of “nobody”, “owners”, “members”
Members (Array of GroupMembership) - a list of each member of the group
App (string) - if this group refers to an App, which app.
ImpersonatedUser (string) - if this group refers to impersonating a user in an app, which user.

GroupMembership

GroupMembership represents the presence of a user in an access control group

User (string) - The user ID.
RequestedTime (RFC3339-formatted timestamp) - When access was first requested.
LastUsed (RFC3339-formatted timestamp) - LastUsed is the time when the user last signed it. It is used to determine if the user’s membership in the group is active. A zero valued time.Time means that the user is inactive.
Reason (string) - Reason is the text that the user provided upon joining the group, if any.
RejectedBy (string) - The ID of the user that blocked membership for this user. If present then the request is rejected and the user is blocked from joining.
RejectedReason (string) - The reason given when blocking membership.
RejectedTime (RFC3339-formatted timestamp) - The time membership was rejected.
ApprovedBy (string) - The ID of the user that approved membership for this user. If present then the user is approved to be a member of the group.
ApprovedReason (string) - The reason given when approving membership.
ApprovedTime (RFC3339-formatted timestamp) - The time membership was approved.

GroupMembershipState

GroupMembershipState represents the state of a user’s membership in a group.

State diagram:

                        Unreject()
                    ┌────────────────┐
                    ↓                │
   ┌───────────→ absent ─────────→ forbidden
   │              │ │               ↑ ↑ ↑
   │         ┌────┘ │ RequestJoin() │ │ │
   │         │      │               │ │ │ Reject()
   │         │      ↓               │ │ │
   │         │  requested ──────────┘ │ │
   │         │      │                 │ │
   │         │      │ Approve()       │ │
   │         └───┐  │                 │ │
   │             ↓  ↓                 │ │
   │       ┌───→ inactive  ───────────┘ │
   │       │        │                   │
   │  Idle │        │ Use()             │
   │       │        │                   │
   │       │        ↓                   │
   │       └──── active  ───────────────┘
   │                │
   └────────────────┘
         Leave()

A string enumeration. Possible values are:

absent - the user is not in the group
requested - the user has requested access to the group
inactive - the user is a member of the group but not active
active - the user is active in the group
forbidden - the user is forbidden from joining the group

HashAlgorithm

HashAlgorithm is the list of algorithms that are supported for password hashing

A string enumeration. Possible values are:

bcrypt2 - is an adaptive hash function based on the Blowfish symmetric block cipher cryptographic algorithm

HostInfo

HostInfo describes a host using information provided by the client

HostName (string) - The name of the host
HostID (string) - An operating-system derived unique identifier for the host.
OS (string) - The operating system
Version (string) - The operating system version.
Device (string) - The manufacturer and model of the user’s device, e.g. “Apple iPad”
Browser (string) - The name of the browser in use
BrowserVersion (string) - the version of the browser.

IM

IM represents an instant messenger account

CustomProtocol (string) - If the protocol value is custom_protocol, this property holds the custom protocol’s string.
CustomType (string) - If the IM type is custom, this property holds the custom type string.
Im (string) - The user’s IM network ID.
Primary (bool) - If this is the user’s primary IM. Only one entry in the IM list can have a value of true.
Protocol (IMProtocol) - An IM protocol identifies the IM network. The value can be a custom network or the standard network. Acceptable values are: ,
Type (IMType) - The type must be one of these values:, custom, home, other, work Acceptable values are:, “custom”, “home”, “other”, “work”

IMProtocol

IMProtocol represents an IM protocol

A string enumeration. Possible values are:

aim - the AOL Instant Messenger protocol
custom_protocol - the A custom IM network protocol
gtalk - the Google Talk protocol
icq - the ICQ protocol
jabber - the Jabber protocol
msn - the MSN Messenger protocol
net_meeting - the Net Meeting protocol
qq - the QQ protocol
skype - the Skype protocol
yahoo - the Yahoo Messenger protocol

IMType

IMType represents a type of IM

A string enumeration. Possible values are:

custom - the “custom” IM type
home - the “home” IM type
other - the “other” IM type
work - the “work” IM type

Icon

Icon is a visual representation of a particular user or app. If ContentType and Image are set then the icon is embedded in the object. If URL is specified then the icon refers to an external resource.

URL (string) - The URL to the icon image.

IntegrityLevel

IntegrityLevel represents the the maximum value of information assets that a session can access

A integer enumeration. Possible values are:

UnknownIntegrity (0) - the integrity level has not been determined
NotTrustedIntegrity (1) - the session cannot access any assets.
LowIntegrity (2) - the session can access non-valuable information assets
MediumIntegrity (3) - the session can access valuable information assets
HighIntegrity (4) - the session can change auth settings & provisioning

IntegrityLevelChangeIntent

IntegrityLevelChangeIntent is returned by the server when responding with a 401 Unauthorized response requiring more integrity than is currently present in the session. It can be passed back to the auth endpoints to display the intent to a user on another device.

Level (IntegrityLevel) - The target integrity level.
Headline (string) - The top level headline of the activity, e.g. “Sign in to TPS Reports”
Subhead (string) - An optional second level headline.
Icon (string) - The public URL to an icon that represents the activity.

JoinApprovalPolicy

JoinApprovalPolicy represents the policy for joining the group.

A string enumeration. Possible values are:

owner - the owner must approve new members
member - any current member of the group can
open - anyone can join.
individual - the anyone in the user’s approver list

KeyPair

KeyPair represents a 4096-bit RSA key and the corresponding certificate chain.

Type (KeyPairType)
CertPEM (base64-encoded binary)

KeyPairType

KeyPairType represents the type of KeyPair

A string enumeration. Possible values are:

root - the key pair is the root key
intermediate - the key pair is an intermediate key
server - the key pair is a server key

KeyPairs

KeyPairs is a list of KeyPair

An array of KeyPair

LDAPApp

LDAPApp represents the LDAP-specific data for an app

Headline (string)
Subhead (string)
Groups (Array of string)
OwnerGroups (Array of string)
Suffix (string)

LifecycleOperation

LifecycleOperation is an enumeration representing the various lifecycle operations

A string enumeration. Possible values are:

Ping - is the LifecycleOperation value for Ping
ListGroups - is the LifecycleOperation value for ListGroups
ListRoles - is the LifecycleOperation value for ListRoles
ListLicenses - is the LifecycleOperation value for ListLicenses
GetAccount - is the LifecycleOperation value for GetAccount
ListAccounts - is the LifecycleOperation value for ListAccounts
CreateAccount - is the LifecycleOperation value for CreateAccount
Invite - is the LifecycleOperation value for Invite
DeleteAccount - is the LifecycleOperation value for DeleteAccount
EnableAccount - is the LifecycleOperation value for EnableAccount
DisableAccount - is the LifecycleOperation value for DisableAccount
SetUsername - is the LifecycleOperation value for SetUsername
AddRole - is the LifecycleOperation value for AddRole
RemoveRole - is the LifecycleOperation value for RemoveRole
SetRoles - is the LifecycleOperation value for SetRoles
AddLicense - is the LifecycleOperation value for AddLicense
RemoveLicense - is the LifecycleOperation value for RemoveLicense
AddGroup - is the LifecycleOperation value for AddGroup
RemoveGroup - is the LifecycleOperation value for RemoveGroup
SetProperty - is the LifecycleOperation value for SetProperty
ClearProperty - is the LifecycleOperation value for ClearProperty

LifecycleRequest

LifecycleRequest represents messages sent to a custom lifecycle agent when it must perform a lifecycle action.

RequestID (string) - an opaque identifier for this request
Operation (LifecycleOperation) - the operation to perform
Body (&{X:json Sel:RawMessage}) - operation-specific data

LifecycleResponse

LifecycleResponse represents a lifecycle agent’s response to a lifecycle request.

RequestID (string) - an opaque identifier for this request
Status (int) - an HTTP-style status code, 200 for success, 4xx or 5xx for errors.
Error (string) - the error message. This field must be present if status >= 400, must not be present if status < 400.
Body (&{X:json Sel:RawMessage}) - operation-specific response data

ListItem

ListItem represents an entry in a list of items

Kind (string) - What kind of object this is, e.g. “App”, or “User”
ID (string) - The object ID.
Href (string) - A relative url to the object, e.g. “/api/v1/apps/wMy2gOdDhuF2En”
Etag (string) - An identifier for a specific version of the object, akin to the way the Etag header is commonly used.
Created (RFC3339-formatted timestamp) - When the object was created.
Updated (RFC3339-formatted timestamp) - When the object was last updated.
Item (any) - The object itself.
StatusCode (int) - if the stream stops processing mid-stream to report an error, this will be the status code for the error. Otherwise it is not present.
Status (string) - if the stream stops processing mid-stream to report an error, this will be the status text for the error. Otherwise it is not present.
Channel (string)

Location

Location represents a position in the world using the WGS84 datum

Lat (float64)
Long (float64)

LocationInfo

LocationInfo represents a geo-coded location. Like a Location, it has Lat and Long, but it also contains information about the name of the place.

Lat (float64)
Long (float64)
City (string)
Locality (string)
Country (string)
TimeZone (string)

LogItem

LogItem represents an item in the audit log.

ID (string) - A unique random identifier for this log item.
Kind (LogKind) - What kind of event this represents.
Created (RFC3339-formatted timestamp) - The time when the operation started.
Updated (RFC3339-formatted timestamp) - The time when the operation most recently changed, typically, when it completed.
Object (string) - The relative URL of the object
ObjectType (string) - what kind of object this is
ObjectTitle (string) - The descriptive name of the object
ObjectIcon (string) - An icon representing the object
SecondaryObject (string) - The relative URL of the object
SecondaryObjectType (string) - what kind of object this is
SecondaryObjectTitle (string) - The descriptive name of the object
SecondaryObjectIcon (string) - An icon representing the object
OldEtag (string)
OldValue (base64-encoded binary)
Etag (string)
Value (base64-encoded binary)
AuthenticatedUser (string) - The ID of the user making the request
AuthenticatedUserTitle (string) - The ID of the user making the request
AuthenticatedUserIcon (string) - The ID of the user making the request
IntegrityLevel (IntegrityLevel) - The integrity level of the session
AuthFactors (Array of string) - A list of the valid authentication factors.
RemoteAddress (string)
Device (string) - The ID of the device making the request.
ImpersonatedUser (string) - The ID of the user on whose behalf the request in being made
ImpersonatedUserTitle (string) - The ID of the user on whose behalf the request in being made
ImpersonatedUserIcon (string) - The ID of the user on whose behalf the request in being made
Messages (Array of LogMessage)

LogKind

LogKind is the type of LogItem.

A string enumeration. Possible values are:

auth - a LogItem of type auth
auth_fail - a LogItem of type auth_fail
auth_radius - a LogItem of type auth_radius
auth_ldap - a LogItem of type auth_ldap
auth_admin_impersonate - a LogItem of type auth_admin_impersonate
user_activate - a LogItem of type user_activate
user_suspend - a LogItem of type user_suspend
user_unsuspend - a LogItem of type user_unsuspend
signin - a LogItem of type signin
ssh_sign - a LogItem of type ssh_sign
group_join - a LogItem of type group_join
group_leave - a LogItem of type group_leave
group_activate - a LogItem of type group_leave
group_reject - a LogItem of type group_leave
group_unreject - a LogItem of type group_leave
create - a LogItem emitted when an object is created
update - a LogItem emitted when an object is updated
delete - a LogItem emitted when an object is deleted

LogMessage

LogMessage represents a message within a log item

Code (int)
Message (string)
Arguments (Array of string)

LogMetadata

LogMetadata represents information about an object captured for log purposes

Type (string)
Title (string)
Icon (string)

LogPage

LogPage represents a stored list of LogItem records.

URL (string)
First (RFC3339-formatted timestamp)
Last (RFC3339-formatted timestamp)
Count (int)

Metadata

Metadata represents object metadata

ID (string) - The object ID.
Href (string) - A relative url to the object, e.g. “/api/v1/apps/wMy2gOdDhuF2En”
Etag (string) - An identifier for a specific version of the object, akin to the way the Etag header is commonly used.
Created (RFC3339-formatted timestamp) - When the object was created.
Updated (RFC3339-formatted timestamp) - When the object was last updated.

Metric

Metric represents one datum for a given metric category

Tags (Tags) - A list of user-defined tags for this object
Name (string) - A descriptive name for the key.
Value (string) - TODO right now to support a wide array of data types
Time (RFC3339-formatted timestamp)
Duration (an RFC3339-formatted duration)

MigrateTaskResult

MigrateTaskResult represents the results of a migration subtask

Name (string)
Success (int)
Errors (Array of string)

MobileDevice

MobileDevice represents a user’s mobile device.

Metadata (Metadata)
Tags (Tags) - A list of user-defined tags for this object
UserID (string) - The user ID of the user owning the device.
EnrollNonce (base64-encoded binary) - The enrollment nonce, if the device is not yet enrolled.
EnrollAuthStateID (string) - The ID of the session that is enrolling the device
Active (bool) - True if the device has been enrolled.
PublicKey (base64-encoded binary) - The device public key.
ApplePushNotificationDeviceToken (base64-encoded binary) - The token for sending messages via Apple Push Notification Service. Present for iOS devices.
FirebaseCloudMessagingDeviceToken (string) - The token for sending messages via Firebase Cloud Messaging. Present for Android devices.
BearerToken (string) - The bearer token the device uses to authenticate
UserAgent (string) - The user agent string presented by the device when last seen.
LastSeen (RFC3339-formatted timestamp) - The time that the device was last seen.
DeviceName (string) - The device name reported by iOS. (https://developer.apple.com/documentation/uikit/uidevice/1620015-name)
DeviceSystemName (string) - The device system name reported by iOS. (see https://developer.apple.com/documentation/uikit/uidevice/1620054-systemname)
DeviceSystemVersion (string) - The device system version reported by iOS. (see https://developer.apple.com/documentation/uikit/uidevice/1620043-systemversion?language=swift)
DeviceModel (string) - The device model reported by iOS. (see https://developer.apple.com/documentation/uikit/uidevice/1620044-model?language=swift)
DeviceIdentifierForVendor (string) - The device identifierForVendor reported by iOS (see https://developer.apple.com/documentation/uikit/uidevice/1620059-identifierforvendor?language=swift)

MobileSigninRequest

MobileSigninRequest represents a request to sign in via the mobile app.

Metadata (Metadata)
Tags (Tags) - A list of user-defined tags for this object
UserID (string)
MobileDeviceID (string)
AuthStateID (string)
Nonce (base64-encoded binary)
ApnsID (string)
FcmID (string)
Complete (bool)
Approved (bool)
Headline (string)
Subhead (string)
Icon (string)
DoNotUseAppID (string)

Name

Name represents a User’s name

FamilyName (string) - The user’s last name. Required when creating a user account.
FullName (string) - The user’s full name formed by concatenating the first and last name values.
GivenName (string) - The user’s first name. Required when creating a user account.

NameIDFormat

NameIDFormat represents a SAML NameID format option

A string enumeration. Possible values are:

urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress - is the urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress NameID format option.
urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified - is the urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified NameID format option.
urn:oasis:names:tc:SAML:2.0:nameid-format:email - is the urn:oasis:names:tc:SAML:2.0:nameid-format:email NameID format option.
urn:oasis:names:tc:SAML:2.0:nameid-format:emailAddress - is the urn:oasis:names:tc:SAML:2.0:nameid-format:emailAddress NameID format option.
urn:oasis:names:tc:SAML:2.0:nameid-format:entity - is the urn:oasis:names:tc:SAML:2.0:nameid-format:entity NameID format option.
urn:oasis:names:tc:SAML:2.0:nameid-format:persistent - is the urn:oasis:names:tc:SAML:2.0:nameid-format:persistent NameID format option.
urn:oasis:names:tc:SAML:2.0:nameid-format:transient - is the urn:oasis:names:tc:SAML:2.0:nameid-format:transient NameID format option.
urn:oasis:names:tc:SAML:2.0:nameid-format:unspecified - is the urn:oasis:names:tc:SAML:2.0:nameid-format:unspecified NameID format option.

NetworkInfo

NetworkInfo describes a network address, it’s IP, ASN and the AS name

Address (string) - The IP address as a string
AS (int) - The autonomous system number
ASName (string) - The name of the autonomous system.

O365App

O365App represents the Office 365 specific data we must track for an app.

Domain (string) - The domain entered by the user at setup time, e.g. example.com.
InitialDomain (string) - The placeholder domain, e.g. example.onmicrosoft.com.
AzureEnvironment (string) - Which environment, one of AzureCloud, AzureChinaCloud, AzureGermanyCloud, or USGovernment.
SAMLSetupTime (RFC3339-formatted timestamp) - The time that SAML was configured.
OAuth2AuthorizationEndpoint (string) - The OAuth2 authorization endpoint.
OAuth2TokenEndpoint (string) - The OAuth2 token endpoint.
MsgraphHost (string) - The hostname to access the Microsoft Graph API.
ServiceAccountUsername (string) - The username of the service account.
DirectoryWatchSubscriptionID (string) - If there is an active subscription to watch for directory changes, this is the subscription ID returned from the Microsoft Graph API.
EnableDirectorySync (bool) - True if users should be synchronized.
EnableSyncGroupFilter (bool) - True if users should be synchronized only if they match the filters in SyncGroupFilter.
SyncGroupFilter (O365GroupFilterList) - A list of user synchronization filters. Users will be synced if they match any of the filters.
AutoProvisionPSTNDevices (bool) - True if inactive users should have their phones auto-enrolled in Voice or SMS call-back.
EnablePasswordCheck (bool) - True if in headless signin mode the user can provide their O365 password in lieu of a PIN

O365GroupFilter

O365GroupFilter represents an Office 365 group that should be included in directory sync.

ID (string) - The Azure Active Directory Group ID.
DisplayName (string) - The display name of the group.
Include (bool) - If true then users in this group should be synchronized.

O365GroupFilterList

O365GroupFilterList represents a list of O365GroupFilter objects

An array of O365GroupFilter

OAuth2AuthStart

OAuth2AuthStart represents the data needed to start an OAuth2 Relying Party flow.

Name (string)
Icon (Icon)
URL (string) - The URL of the OAuth2.0 authorize endpoint

OAuth2FactorState

OAuth2FactorState represents the state of an OAuth2 device.

FactorState (FactorState)
Icon (Icon)
Name (string)
AppID (string)

OAuth2FactorStates

OAuth2FactorStates is a list of OAuth2FactorState

An array of OAuth2FactorState

Organization

Organization represents the organizations the user belongs to.

CostCenter (string) - The cost center of the user’s organization.
CustomType (string) - If the value of type is custom, this property contains the custom type.
Department (string) - Specifies the department within the organization, such as ‘sales’ or ‘engineering’.
Description (string) - The description of the organization.
Domain (string) - The domain the organization belongs to.
FullTimeEquivalent (int64)
Location (string) - The physical location of the organization. This does not need to be a fully qualified address.
Name (string) - The name of the organization.
Primary (bool) - Indicates if this is the user’s primary organization. A user may only have one primary organization.
Symbol (string) - Text string symbol of the organization. For example, the text symbol for Google is GOOG.
Title (string) - The user’s title within the organization, for example ‘member’ or ‘engineer’.
Type (OrganizationType) - The type of organization. Acceptable values are:, “domain_only”, “school”, “unknown”, “work”,

OrganizationType

OrganizationType represents the type of an Organization

A string enumeration. Possible values are:

domain_only - an Organization of type domain_only
school - an Organization of type school
unknown - an Organization of type unknown
work - an Organization of type work

OtherSession

OtherSession represents the state of another session

AuthStateID (base64-encoded binary) - The ID of the other session
DeviceID (string) - The device ID of the other session
Location (LocationInfo) - information about the proported physical location of the other session.
Network (NetworkInfo) - information about the network attachment of the other session.
HostInfo (HostInfo) - information about the other host.
Intent (IntegrityLevelChangeIntent)

PSTNDevice

PSTNDevice represents a PSTN device registered to a user.

ID (string) - A unique identifier for the device.
Name (string) - A user defined name for the device.
Number (string) - the device’s phone number, in international format, e.g., +12125551212
Verified (bool) - True if the device was verified
Created (RFC3339-formatted timestamp) - When the device was created.
Voice (bool) - Perform a voice call rather than an PSTN.

PSTNDevices

PSTNDevices is a list of PSTN devices

An array of PSTNDevice

PSTNFactorState

PSTNFactorState represents the auth state of a PSTN device.

FactorState (FactorState)
ID (string)
Name (string)
Number (string)
Voice (bool)

Password

Password represents a hashed password

Metadata (Metadata)
Tags (Tags) - A list of user-defined tags for this object
HashAlgorithm (HashAlgorithm) - The HashAlgorithm that was used to hash the password originally
AppID (string) - The app ID of the app this password is for
UserID (string) - The user ID of the user whose password this is
ComplexityScore (int) - The password complexity score as computed by zxcvbn

Phone

Phone represents a user’s phone.

CustomType (string) - If the value of type is custom, this property contains the custom type.
Primary (bool) - Indicates if this is the user’s primary phone number. A user may only have one primary phone number.
Type (PhoneType) - The type of phone number.
Value (string) - A human-readable phone number. It may be in any telephone number format.

PhoneType

PhoneType represents the type of Phone

A string enumeration. Possible values are:

assistant - a Phone of type “assistant”
callback - a Phone of type “callback”
car - a Phone of type “car”
company_main - a Phone of type “company_main”
custom - a Phone of type “custom”
grand_central - a Phone of type “grand_central”
home - a Phone of type “home”
home_fax - a Phone of type “home_fax”
isdn - a Phone of type “isdn”
main - a Phone of type “main”
mobile - a Phone of type “mobile”
other - a Phone of type “other”
other_fax - a Phone of type “other_fax”
pager - a Phone of type “pager”
radio - a Phone of type “radio”
telex - a Phone of type “telex”
tty_tdd - a Phone of type “tty_tdd”
work - a Phone of type “work”
work_fax - a Phone of type “work_fax”
work_mobile - a Phone of type “work_mobile”
work_pager - a Phone of type “work_pager”

PingboardApp

PingboardApp holds Pingboard-specific data for an App.

ClientID (string)

PosixAccount

PosixAccount represents POSIX account information for the user.

AccountID (string)
Gecos (string) - The GECOS (user information) for this account.
Gid (int) - The default group ID.
HomeDirectory (string) - The path to the home directory for this account.
OperatingSystemType (string)
Primary (bool) - If this is user’s primary account within the SystemId.
Shell (string) - The path to the login shell for this account.
SystemID (string) - System identifier for which account Username or Uid apply to.
UID (int) - The POSIX compliant user ID.
Username (string) - The username of the account.

RadiusApp

RadiusApp represents the Radius-specific data for an app

SecondFactorOnly (bool) - If true then the signin process does not require a password or PIN, but rather assumes that a PIN has been provided externally. Use this with caution, obviously.

Relation

Relation represents the user’s relationships to other users.

CustomType (string) - If the value of type is custom, this property contains the custom type.
Type (RelationType) - The type of relation. Acceptable values are:
Value (string) - The name of the person the user is related to.

RelationType

RelationType represents the type of a Relation

A string enumeration. Possible values are:

admin_assistant - a Relation of type “admin_assistant”
assistant - a Relation of type “assistant”
brother - a Relation of type “brother”
child - a Relation of type “child”
custom - a Relation of type “custom”
domestic_partner - a Relation of type “domestic_partner”
dotted_line_manager - a Relation of type “dotted_line_manager”
exec_assistant - a Relation of type “exec_assistant”
father - a Relation of type “father”
friend - a Relation of type “friend”
manager - a Relation of type “manager”
mother - a Relation of type “mother”
parent - a Relation of type “parent”
partner - a Relation of type “partner”
referred_by - a Relation of type “referred_by”
relative - a Relation of type “relative”
sister - a Relation of type “sister”
spouse - a Relation of type “spouse”

RemoteAgent

RemoteAgent represents an agent that connects and performs work for you or an application.

Name (string)
Tags (Tags) - A list of user-defined tags for this object
App (string)
LastSeen (RFC3339-formatted timestamp)
Connections (Array of RemoteAgentConnection)

RemoteAgentConnection

RemoteAgentConnection represents a past connection to the service

RemoteAddress (string)
StartTime (RFC3339-formatted timestamp)

SSHKey

SSHKey represents the user’s SSH public keys

Fingerprint (string) - THe fingerprint of the combined public key.
PubKey (string) - The combined public key.
FirstPartyFingerprint (string) - For split ECDSA, the fingerprint of the client part of the key.
FirstPartyPubKey (string) - For split ECDSA, the public key of the client part of the key.
SecondPartyKey (Secret)
Comment (string) - The SSH key comment.
Created (RFC3339-formatted timestamp) - When the key was created.

SSORequest

SSORequest is the message sent to the server to exchange a SAML request for a SAML response.

RelayState (string) - The SAML relay state parameter.
Request (string) - The original SAML request.
RequestIsCompressed (bool) - True if the original SAML request is compressed with zlib.
RetryToken (string) - A signed token that establishes the initial time the SAML request was received.
ImpersonatedUser (string) - If given, then sign in as the indicated user ID rather than the currently signed in user. May require additional authorization.

SSOResponse

SSOResponse is the message received from the server in response to a signin request. It can contain a SAML response, but may also contain a delivered credential, or a URL to navigate to.

URL (string) - A URL that the browser should navigate to.
SAMLResponse (string) - A SAML response.
RelayState (string) - The SAML relay state.
RetryToken (string) - If the request will need to be retried for some reason, this signed token establishes the initial time the request was received. It should be passed back in a subsequent SSORequest.
BrowserState (BrowserState) - Browser state (i.e. cookies) that should be applied to the browser.
DeliveredCredential (DeliveredCredential) - Credentials that should be used to sign in via the extension.

SalesforceApp

SalesforceApp represents the Salesforce specific data we must track for an app.

ServerCertificate (base64-encoded binary)
OAuth2TokenID (string)
OAuth2IssuedAt (string)
OAuth2Signature (string)
OAuth2IDToken (string)
Groups (Array of SalesforceGroup)

SalesforceGroup

SalesforceGroup represents an available Salesforce user group.

ID (string)
Name (string)
Email (string)
OwnerID (string)

SamlIDP

SamlIDP represents the setting for the SAML identity provider for this tenant

KeyDER (base64-encoded binary)
CertASN1 (base64-encoded binary)

Script

Script represents a script

Metadata (Metadata)
Tags (Tags) - A list of user-defined tags for this object
Name (string)
Enabled (bool)
Content (base64-encoded binary)
Exports (Array of string)
Tests (Array of ScriptTest)

ScriptLog

ScriptLog records a script having executed

Metadata (Metadata)
Tags (Tags) - A list of user-defined tags for this object
ScriptID (string)
Component (string)
Method (string)
Input (Array of base64-encoded binary)
Output (base64-encoded binary)
Error (string)
Log (Array of string)

ScriptTest

ScriptTest represents a test case for a script

Name (string)
Component (string)
Method (string)
Input (Array of base64-encoded binary)
Output (base64-encoded binary)

ServiceToken

ServiceToken represents a token that identifies a service account. Secret is used to initialize the service account on the first request. Beyond the first request it is not used for authentication or authorization.

TenantID (string) - The tenant ID.
AppID (string) - The app ID.
Secret (string) - The secret part of the token.

SetupCommand

SetupCommand represents a command that the user can run in their terminal to set up an application.

POSIX (string) - A command to run on POSIX systems like Mac or Linux.
Windows (string) - A command to run on Windows.
Docker (string) - A Docker command line, if applicable.
ConfigFile (string) - An example configuration file, if applicable.

ShortLink

ShortLink represents a redirection

Tags (Array of string) - A list of user-defined tags for this object
Target (string) - the full URL. Take care not to create an open redirector
TenantID (string)
TTL (an RFC3339-formatted duration) - the link should be made inactive this long after Created

SignupParam

SignupParam is a parameter provided by the user to the initial signup URL

Name (string)
Value (string)

SlackApp

SlackApp represents a Slack app integration

cert (base64-encoded binary)

Tenant

Tenant represents the global configuration for your instance of groove.id.

Name (string) - The name of your organization.
Icon (Icon) - Icon is an image representing the company. PNG, or SVG preferred.
EmailDomains (Array of string) - EmailDomains is a list of allowed email address domains. If the list is empty, then any domain is allowed.
CanonicalVirtualHost (string) - The immutable sign in host, e.g. t9guobjksehkmk.auth.groove.id.
PreferredVirtualHost (string) - The default host used to sign in, e.g. signin.example.com.
Active (bool) - Active is true then you have completed the setup process.
KeyPairs (KeyPairs) - A list of various cryptographic keys used on your behalf.
PrimaryUserID (string) - The ID of the first user created.
ActivateUserRequiresCode (bool) - If true then activating a new user requires an activation code.
ThemeColor (string) - An HTML color like ‘red’ or ‘#FF0000’ that represents your organizations main color.
FeatureFlags (FeatureFlags) - A list of special flags enabled for your account.
ListUsersRequiresAdmin (bool) - True if only administrators are allowed to view the list of users.
CreateAppsRequiresAdmin (bool) - True if only administrators are allowed to create new apps. Otherwise, any user can create an app.
EnablePSTN (bool) - True if SMS or voice call based authentication is enabled (not recommended)
EnableOTP (bool) - True if email based one-time codes (OTP) are allowed (not recommended)
EnablePasswords (bool) - True if Passwords are enabled (not recommended)
HideEmailDomain (bool) - True the domain component of the UI will be hidden in the log in view
Wallpaper (Icon) - The URL for a custom background image for the signin view
Departments (Array of string) - List of departments at the company
PSTNCallFrom (string) - The PSTN telephone number that outgoing calls appear to come from.
LicenseType (string)
LicenseExpires (RFC3339-formatted timestamp)

U2FAuthStart

U2FAuthStart is the response to the /auth/u2f/start endpoint

Challenge (base64-encoded binary) - The U2F Challenge
KeyHandles (Array of base64-encoded binary) - A list of the enrolled U2F key handles for the current origin.
AlternateOrigins (Array of string) - A list of other origins that have U2F devices enrolled.

U2FDevice

U2FDevice represents a U2F device registered to a user.

ID (string) - A unique identifier for the device.
Name (string) - A user defined name for the device
Challenge (base64-encoded binary) - The U2F Challenge
Created (RFC3339-formatted timestamp) - When the device was created.
RegisteredOrigin (string) - The origin that the device was registered in.
KeyHandle (base64-encoded binary) - The U2F key handle

U2FDevices

U2FDevices is a list of U2F devices

An array of U2FDevice

UnattendedDeviceListItem

UnattendedDeviceListItem represents an item in the list of unattended devices

DeviceID (string)
LastSignin (RFC3339-formatted timestamp)
Location (LocationInfo) - information about the proported physical location of the other session.
Network (NetworkInfo) - information about the network attachment of the other session.
HostInfo (HostInfo) - information about the other host.

User

User represents an individual person.

Active (bool) - True if the user has been set up already.
SuspendAfter (RFC3339-formatted timestamp)
SuspendBefore (RFC3339-formatted timestamp)
Deleted (bool) - True if the user has been deleted.
Tags (Tags) - A list of user-defined tags for this object
IsAdmin (bool) - True if the user has administrative privileges.
IsHelpDesk (bool) - True if the user can create a user (stand-in for helpdesk group)
FailedPINTime (RFC3339-formatted timestamp) - The last time that the user incorrectly entered their PIN
FailedPINCount (int) - The number of times the user has incorrectly entered their pin since the last success.
FailedTOTPTime (RFC3339-formatted timestamp) - The last time the user incorrectly entered a TOTP code
FailedTOTPCount (int) - The number of times the user has incorrectly entered a TOTP code since the last correct code.
FailedPasswordTime (RFC3339-formatted timestamp) - The last time the user incorrectly entered a password
FailedPasswordCount (int) - The number of times the user has incorrectly entered a password since the last correct code.
ReferenceVideo (string) - An internal reference to a blob containing the user’s reference video.
ReferenceVideoWords (Array of string) - The words used in the reference video.
U2FDevices (U2FDevices) - A list of the users registered U2F devices.
PSTNDevices (PSTNDevices) - A list of the users registered SMS or voice call devices.
BackupCodes (BackupCodes) - A list of the users backup codes.
UnattendedDevices (Array of string) - A list of the user’s devices that should be signed in automatically, without friction.
Addresses (Array of Address) - A list of the user’s addresses.
Aliases (Array of string) - List of the user’s alias email addresses.
Emails (Array of Email) - A list of the user’s email addresses.
ExternalIDs (ExternalIDs) - A list of external IDs for the user, such as an employee or network ID.
IMs (Array of IM) - The user’s Instant Messenger (IM) accounts. A user account can have multiple ims properties. But, only one of these ims properties can be the primary IM contact.
Locations (Array of UserLocation) - Where the user is located
Name (Name) - Holds the given and family names of the user, and the read-only fullName value. The maximum number of characters in the givenName and in the familyName values is 60. In addition, name values support unicode/UTF-8 characters, and can contain spaces, letters (a-z), numbers (0-9), dashes (-), forward slashes (/), and periods (.). For more information about character usage rules, see the administration help center.
Department (string) - the department of the company the user belongs to. Departments are derived from the tenant departments field
Title (string) - Job title
Description (string) - Description of the user
UserPrincipalName (string) - User login name is in format of testUser@DomainName.com. It is an internet-style login name for the user based on Internet standard RFC 822. It should be unique among all security principal objects within the directory forest
SAMAccountName (string) - User login name is in the format of DomainName\testUser.It should be less than 20 characters. It should be unique among all security principal objects within the domain.
Organizations (Array of Organization) - List of organizations the user belongs to.
Phones (Array of Phone) - A list of the user’s phone numbers.
PosixAccounts (Array of PosixAccount) - A list of POSIX account information for the user.
Relations (Array of Relation) - A list of the user’s relationships to other users.
SSHKeys (Array of SSHKey) - A list of SSH public keys.
Icon (Icon) - the user’s avatar
Websites (Array of Website) - Websites of the user.
FeatureFlags (Array of FeatureFlag) - A list of feature flags enabled for this user.
Approvers (Array of string) - A list of the users authorized to approve this user’s access
Locale (string)
TourStepCompleted (int)

UserApp

UserApp represents user settings for an application

AppID (string) - The ID of the application in question
Username (string) - The username
PasswordLastChanged (RFC3339-formatted timestamp) - The time the password was last changed.
ImpersonationGroupID (string) - The ID of a group that authorizes impersonation in this app as this user.
DesiredState (AccountState) - the desired state of the account
DesiredFeatures (Array of string) - which features to enable in the account. App specific, e.g. “admin”, “pro”, etc.
AccountID (string)
StateLastUpdate (RFC3339-formatted timestamp) - the time the account was last updated
StateLastError (string)
State (AccountState) - the current state of the account
Features (Array of string) - which features are enabled in the account

UserApps

UserApps is a list of UserApps

An array of UserApp

UserIdentityKind

UserIdentityKind represents a way of providing user information

A string enumeration. Possible values are:

email - the user information provided will be the email address.
unix - the user information provided will be the unix user name (i.e. the part of the email address before the @)
id - the user information provided will be the Groove.id user ID (e.g. uqrzscjdl0akpw).
first_name - the user information provided will be the first name.
last_name - the user information provided will be the last name.
full_name - the user information provided will be the full name.

UserLocation

UserLocation represents the normative location where a user is stationed. (This is e.g where their desk is, rather than their GPS coordicates)

Area (string) - Textual location. This is most useful for display purposes to concisely describe the location. For example, “Mountain View, CA”, “Near Seattle”.
BuildingID (string) - Building identifier.
CustomType (string) - If the location type is custom, this property contains the custom value.
DeskCode (string) - Most specific textual code of individual desk location.
FloorName (string) - Floor name/number.
FloorSection (string) - Floor section. More specific location within the floor. For example, if a floor is divided into sections “A”, “B”, and “C”, this field would identify one of those values.
Type (UserLocationType) - The location type.

UserLocationType

UserLocationType represents a type of a UserLocation

A string enumeration. Possible values are:

custom - a UserLocation of type custom
default - a UserLocation of type default
desk - a UserLocation of type desk

UserMergeSuggestion

UserMergeSuggestion represents the suggestion that two users should be merged.

FromUserID (string) - the ID of the user to merge from
ToUserID (string) - the ID of the user to merge to
Reason (string) - a human readable english string indicating the reason for the merge
Confidence (float64) - a value between 0.0 and 1.1 indicating how confident we are in the match
AppConflicts (Array of string)

VirtualHost

VirtualHost represents a single virtual host provided by the server.

Tags (Tags) - A list of user-defined tags for this object
Cert (base64-encoded binary) - The TLS certificate for this host.
Key (base64-encoded binary) - The TLS key. (Can be used to create or update the host, but will not be present in responses from the server.)
AutoHTTPS (bool) - True if the certificate should be generated automatically on demand.
App (string) - If this is an ‘app’ virtualhost, then this is the ID of the app in question.
Health (VirtualHostHealth)
LastAlertTime (RFC3339-formatted timestamp)
LastAlertError (string)

VirtualHostHealth

VirtualHostHealth describes the health status of a virtualhost

LastCheck (RFC3339-formatted timestamp)
DNSError (string)
DNSRecord (string)
CertificateError (string)
CertificateThumbprint (string)
CertificateExpiration (RFC3339-formatted timestamp)

VouchAuthStart

VouchAuthStart is the response to the /auth/vouch/start endpoint

ID (string)
URL (string)
MagicWords (Array of string)
State (VouchRequestState)

VouchPeerChoice

VouchPeerChoice is a peer that could be selected for vouching.

Avatar (base64-encoded binary) - An image representing the user
Name (Name) - The name of the user
UserID (string) - The user’s ID.
Available (bool) - True if the user is online.

VouchRequest

VouchRequest represents a request to vouch for someone.

Tags (Tags) - A list of user-defined tags for this object
VideoURL (string) - The URL of the video of the person saying the magic words.
State (VouchRequestState) - The current state of the vouch request.
UserID (string) - The user ID of the person being vouched for.
AuthStateID (string) - The session ID of the person being vouched for.
PeerUserID (string) - The user ID of the person doing the vouching.
PeerAuthStateID (string) - The session ID of the person doing the vouching.
MagicWords (Array of string) - The magic works that the person actually said.
MagicWordChoice1 (Array of string) - The first option of the multiple choices the voucher has for the magic words.
MagicWordChoice2 (Array of string) - The second option of the multiple choices the voucher has for the magic words.
MagicWordChoice3 (Array of string) - The third option of the multiple choices the voucher has for the magic words.
ShortCode (string) - The short code for this vouch request
ShortURL (string) - The short URL for this vouch request.

VouchRequestState

VouchRequestState represents the state of a vouch request

A integer enumeration. Possible values are:

VouchRequestRecording (0) - we are waiting for the user to
VouchRequestWaiting (1) - the vouch request is waiting for
VouchRequestChecking (2) - the vouch request is being checked
VouchRequestAccepted (3) - the vouch request has been approved
VouchRequestError (4) - the vouch request has failed for
VouchRequestRejected (5) - the vouch request has failed for fraud
VouchRequestCanceled (6) - the requestor canceled the request

VoucherAnswer

VoucherAnswer represents the response a voucher sends.

Choice (VoucherChoice) - Which choice the voucher made.
Words (Array of string) - Which words the voucher selected
Comment (string) - The comment the voucher added.
FraudSuspected (bool) - True if the voucher suspects this is fraudulent.

VoucherChoice

VoucherChoice represents the decision made by a voucher

A integer enumeration. Possible values are:

VoucherChoiceNone (0) - no choice has been made
VoucherChoiceIdentified (1) - voucher positively identifies the person
VoucherChoiceFraud (2) - the voucher believes the person in the video is not
VoucherChoiceNotRecognized (3) - the voucher cannot identify the person in the
VoucherChoiceVideoDefective (4) - the voucher cannot see or hear the person in the

VoucherQuestion

VoucherQuestion represents the question we ask a voucher.

ID (string) - The ID of the Vouch request.
Created (RFC3339-formatted timestamp) - when the vouch request was created.
IsNew (bool) - True if the vouch request is for a new user account.
TrainingWin (bool) - True if the previous VoucherAnswer correctly identified that the magic words were not among the actual choices.
VoucheeName (Name) - The name of the person being vouched for.
WordChoices (Array of Array of string) - The available choices of magic words.

WebexApp

WebexApp represents the Adobe-specific data for an App.

Organizations (Array of WebexOrganization)

WebexOrganization

WebexOrganization represents a Webex organization that the user might choose to manage.

ID (string)
Name (string)

Website

Website represents a reference to a user’s website

CustomType (string) - The custom type. Only used if the type is custom.
Primary (bool) - If this is user’s primary website or not.
Type (WebsiteType) - The type or purpose of the website. For example, a website could labeled as home or blog. Alternatively, an entry can have a custom type. Custom types must have a customType value.
Value (string) - The URL of the website.

WebsiteType

WebsiteType represents the type of a Website

A string enumeration. Possible values are:

app_install_page - a Website of type = “app_install_page”
blog - a Website of type “blog”
custom - a Website of type “custom”
ftp - a Website of type “ftp”
home - a Website of type “home”
home_page - a Website of type “home_page”
other - a Website of type “other”
profile - a Website of type “profile”
reservations - a Website of type “reservations”
work - a Website of type “work”

WorkflowApp

WorkflowApp holds Workflow-specific data for an App.

CreateDescription (string)
DeleteDescription (string)
DisableDescription (string)
CanDisableAccount (bool)
CanDeleteAccount (bool)
CanDeliverPassword (bool)
GenerateInitialPassword (bool)
AssignToUser (bool)
Assignees (Array of string)
ReminderIntervalHours (int) - 0 means don’t remind
SnoozeIntervalHours (int) - 0 means don’t snooze
NotifyUserOnCreate (bool)
NotifyUserOnCreateMessage (string)
DeliverPasswordOnCreate (bool)
Properties (Array of WorkflowAppAccountProperty)

WorkflowAppAccountProperty

WorkflowAppAccountProperty represents a property that

Name (string)
Standard (string)
Description (string)
ShowBeforeCreate (bool)
ShowAfterCreate (bool)
Obscured (bool)

WorkflowLogEntry

WorkflowLogEntry represents an item in the AccountChange’s workflow log.

Time (RFC3339-formatted timestamp) - The time when the change occurred.
User (string) - The ID of the user doing the action, or an empty string if done by the system.
StatusCode (int) - The HTTP status code describing the action.
Status (string) - An English, human readable description of the action.

WorkflowUpdate

WorkflowUpdate represents the request body of the /accountchanges/:accountchangeid/workflow/{complete,cancel,snooze} API endpoints

Error (bool)
Message (string)
Properties (Array of AccountProperty)

Last modified May 12, 2020: refactor docs (393857667)