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 (Array of AppRole) - 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.
  • 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
  • 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.

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.

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.
  • 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.
  • 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)

AppAccount

AppAccount represents a user’s account in a third-party application.

  • ID (string) - The unique identifier of this account according to the upstream application.
  • AppID (string) - The ID of the application in Groove.id
  • UserID (string) - The ID of the user in Groove.id
  • Name (string) - The account holder’s name according to the application
  • Email (string) - The account holder’s email address according to the application
  • State (AccountState) - The state of the account in the upstream application
  • Features (Tags) - The application-specific features enabled for this account

AppCustomAttribute

AppCustomAttribute represents custom attributes added to the SAML assertion.

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)

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.

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

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.

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

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

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

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.

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

  • 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)
  • Tags (Tags) - A list of user-defined tags for this object

MobileDevice

MobileDevice represents a user’s mobile device.

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.
  • ServiceAccountPassword (Secret)
  • 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.

OAuth2FactorStates

OAuth2FactorStates is a list of OAuth2FactorState

An array of OAuth2FactorState

OldAuthResponse

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

  • Metadata (Metadata)
  • NeedEmail (bool) - If true then we need an email address from the user.
  • IntegrityLevel (IntegrityLevel) - The current integrity level achieved.
  • CanEnroll (bool) - If true then the user is not currently set up and should be enrolled.
  • 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.
  • PSTN (FactorState) - Tells if the user can, must, or has provided an SMS or voice code.
  • 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.
  • TOTPSecret (string) - If enrolling TOTP, the TOTP secret
  • TOTPImage (base64-encoded binary) - If enrolling TOTP, the TOTP enrollment QR code image
  • U2FChallenge (base64-encoded binary) - The U2F Challenge
  • U2FKeyHandles (Array of base64-encoded binary) - A list of the enrolled U2F key handles for the current origin.
  • U2FAlternateOrigins (Array of string) - A list of other origins that have U2F devices enrolled.
  • OAuth2 (Array of OldOAuth2)
  • UserID (string) - The current user ID.
  • MagicWords (Array of string) - The magic words used for a video vouch.
  • MobileEnrollQR (base64-encoded binary) - If enrolling a mobile device, the enrollment QR image.
  • PSTNDevices (Array of PSTNDevice) - The available PSTN devices (for SMS or voice authentication)
  • MobileAppShouldUpgrade (bool) - True is the user’s mobile app needs to be upgraded.
  • MobileRegistrationIsStale (bool) - True is the user’s mobile app registration may have expired.

OldOAuth2

OldOAuth2 represents an opportunity to authenticate by delegating to an OAuth 2.0 provider.

  • Name (string)
  • Icon (Icon)
  • AppID (string) - The ID of the app which handles the signin flow.
  • FactorState (FactorState)

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)
  • 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 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)

Tags

Tags represents a list of labels attached to an object.

An array of string

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

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) - json:"-"
  • LastAlertError (string) - json:"-"

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

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.

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”