IAM Module Resources

The Identity and Access Management (IAM) module provides a set of resources for managing user authentication, authorization, and access control within the Aidbox.

Overview

IAM module includes the following resource types:

• AccessPolicy

• TokenIntrospector

• Role

• User

• Scope

• Client

• Grant

• Session

• Notification

• NotificationTemplate

• Registration

• IdentityProvider

• AuthConfig

AccessPolicy

Path	Card.	Type	Description
matcho	0..1	Object	Defines rules using the Matcho pattern-matching syntax.
clj	0..1	string	Clojure code that defines access policy rules. DEPRECATED. DO NOT USE IT.
schema	0..1	Object	JSON Schema used to validate requests against the policy.
_source	0..1	string	System Property. DO NOT USE IT.
module	0..1	string	Module that this policy belongs to.
or	0..*	Object	A list of conditions where at least one must be satisfied for the policy to grant access.
roleName	0..1	string	Symbolic link to Role by name
and	0..*	Object	A list of conditions that must all be satisfied for the policy to grant access.
link	0..*	Reference	References to resources associated with this policy. Allowed references: Client, User, Operation
source	0..1	string	Source identifier for the policy.
type	0..1	string	The type or category of the access policy. Allowed values: scope | rest | rpc
engine	0..1	string	Specifies the evaluation engine used for the policy. Allowed values: json-schema | allow | sql | complex | matcho | clj | matcho-rpc | allow-rpc | signed-rpc | smart-on-fhir
rpc	0..1	Object	Defines rules for Remote Procedure Calls (RPCs).
sql	0..1	BackboneElement	SQL-based policy definition.
sql.query	0..1	string	SQL query used to evaluate access conditions.
description	0..1	string	A textual description of the access policy.

TokenIntrospector

Path	Card.	Type	Description
type	1..1	string	Specifies the type of token to introspect. Allowed values: opaque | jwt | aspxauth
jwks_uri	0..1	string	A URL pointing to a JSON Web Key Set (JWKS). When type is jwt the introspector retrieves public keys from this URI to validate token signatures.
jwt	0..1	BackboneElement	Configuration for local JWT validation used when type is jwt.
jwt.iss	0..1	string	The expected issuer (iss) claim value for JWTs. The TokenIntrospector ensures that tokens it validates come from this issuer.
jwt.secret	0..1	string	A shared secret key or other signing key material used to verify the JWT's signature.
introspection_endpoint	0..1	BackboneElement
introspection_endpoint.url	0..1	string	The fully qualified URL of the remote introspection endpoint.
introspection_endpoint.authorization	0..1	string	The authorization header value (e.g. a Basic Auth or Bearer token) used when calling the introspection endpoint. If present it will be included in the request headers.
identity_provider	0..1	Reference	Link to Identity provider associated with the token introspector. Allowed references: IdentityProvider

Role

User role

Path	Card.	Type	Description
name	1..1	string	Role name is a string that defines role. To assign the same role to multiple users, create multiple Role resources with the same "name". [Search param: name => type string]
description	0..1	string	Text description of the role
user	1..1	Reference	Reference to a User resource for which the role will be applied. [Search param: user => type reference] Allowed references: User
links	0..1	BackboneElement	You may list resources here, which can later be granted access for the user with this role via an AccessPolicy resource.
links.patient	0..1	Reference	Reference to Patient resource Allowed references: Patient
links.practitionerRole	0..1	Reference	Reference to PractitionerRole resource Allowed references: PractitionerRole
links.practitioner	0..1	Reference	Reference to Practitioner resource Allowed references: Practitioner
links.organization	0..1	Reference	Reference to Organization resource Allowed references: Organization
links.person	0..1	Reference	Reference to Person resource Allowed references: Person
links.relatedPerson	0..1	Reference	Reference to RelatedPerson resource Allowed references: RelatedPerson
context	0..1	Object

User

Path	Card.	Type	Description
entitlements	0..*	BackboneElement	A list of entitlements for the User that represent a thing the User has.
entitlements.value	0..1	string	The value of an entitlement.
entitlements.display	0..1	string	A human-readable name, primarily used for display purposes (READ-ONLY).
entitlements.type	0..1	string	A label indicating the attribute's function.
entitlements.primary	0..1	boolean	Indicates if this is the primary entitlement. Only one may be 'true'.
profileUrl	0..1	uri	A fully qualified URL pointing to a page representing the User's online profile.
department	0..1	string	Identifies the name of a department.
preferredLanguage	0..1	string	The User's preferred written or spoken language, e.g. 'en_US'.
securityLabel	0..*	BackboneElement	List of security labes associated to the user
securityLabel.system	0..1	string	Code system
securityLabel.code	0..1	string	Code value
ims	0..*	BackboneElement	Instant messaging addresses for the User.
ims.value	0..1	string	Instant messaging address.
ims.display	0..1	string	A human-readable name, primarily for display (READ-ONLY).
ims.type	0..1	string	A label indicating the IM type, e.g. 'aim', 'gtalk'.
ims.primary	0..1	boolean	Indicates if this is the primary IM. Only one may be 'true'.
timezone	0..1	string	The User's time zone in the 'Olson' format, e.g. 'America/Los_Angeles'.
displayName	0..1	string	The name of the User, suitable for display to end-users.
twoFactor	0..1	BackboneElement	Two factor settings for user
twoFactor.enabled	1..1	boolean	Defines whether two-factor auth is currently enabled.
twoFactor.transport	0..1	string	Transport of 2FA confirmation code (if used).
twoFactor.secretKey	1..1	string	TOTP Secret key.
gender	0..1	string	The user's gender.
email	0..1	email	Primary email for the user.
userType	0..1	string	Identifies the relationship between the organization and the user (e.g. 'Employee', 'Contractor').
division	0..1	string	Identifies the name of a division.
name	0..1	BackboneElement	The components of the user's real name (formatted, family, given, etc.).
name.formatted	0..1	string	Full name, including titles and suffixes, formatted for display.
name.familyName	0..1	string	Family name (last name in Western languages).
name.givenName	0..1	string	Given name (first name in Western languages).
name.middleName	0..1	string	The middle name(s) of the User.
name.honorificPrefix	0..1	string	Honorific prefix (title), e.g. 'Ms.'.
name.honorificSuffix	0..1	string	Honorific suffix, e.g. 'III'.
locale	0..1	string	Indicates the User's default location for localization (e.g., currency, date format).
fhirUser	0..1	Reference	A reference to a related FHIR resource Allowed references: Patient, Practitioner, Person
identifier	0..*	Identifier	A list of identifiers for the user.
photo	0..1	uri	Primary photo for the user.
phoneNumber	0..1	string	Primary phone number.
userName	0..1	string	Unique identifier for the User, typically used to directly authenticate. Must be unique across the service provider's Users.
addresses	0..*	BackboneElement	A physical mailing address for this User (e.g. 'work', 'home').
addresses.formatted	0..1	string	Full address, formatted for display or mailing label.
addresses.streetAddress	0..1	string	Street address component (may contain newlines).
addresses.locality	0..1	string	City or locality component.
addresses.region	0..1	string	State or region component.
addresses.postalCode	0..1	string	Zip code or postal code.
addresses.country	0..1	string	Country name component.
addresses.type	0..1	string	A label indicating the address type, e.g. 'work' or 'home'.
title	0..1	string	The user's title, e.g. 'Vice President'.
link	0..*	BackboneElement	A collection of references or links associated with the user.
link.link	0..1	Reference	A referenced resource link.
link.type	0..1	string	A label indicating the link's function.
employeeNumber	0..1	string	Numeric or alphanumeric identifier assigned to a person by the organization.
password	0..1	password	The User's cleartext password, used for initial or reset scenarios.
photos	0..*	BackboneElement	URLs of photos of the user.
photos.value	0..1	uri	URL of a photo of the User.
photos.display	0..1	string	A human-readable name, primarily used for display purposes (READ-ONLY).
photos.type	0..1	string	A label indicating 'photo' or 'thumbnail'.
photos.primary	0..1	boolean	Indicates if this is the primary photo. Only one may be 'true'.
manager	0..1	Reference	Another User resource who is this User's manager. Allowed references: User
x509Certificates	0..*	BackboneElement	A list of certificates issued to the User.
x509Certificates.value	0..1	base64Binary	The value of an X.509 certificate (base64).
x509Certificates.display	0..1	string	A human-readable name, primarily used for display purposes (READ-ONLY).
x509Certificates.type	0..1	string	A label indicating the certificate's function.
x509Certificates.primary	0..1	boolean	Indicates if this is the primary certificate. Only one may be 'true'.
emails	0..*	BackboneElement	Email addresses for the user. Values should be canonicalized (e.g. '[e-mail]').
emails.value	0..1	string	An individual email address (canonicalized).
emails.display	0..1	string	A human-readable name for display purposes (READ-ONLY).
emails.type	0..1	string	A label indicating the attribute's function, e.g. 'work', 'home'.
emails.primary	0..1	boolean	Indicates if this is the primary email. Only one primary may be 'true'.
inactive	0..1	boolean	A Boolean value indicating the User's administrative status.
active	0..1	boolean	NB: this attr is ignored. Indicates the User's administrative status.
phoneNumbers	0..*	BackboneElement	Phone numbers for the User, e.g. 'tel:[phone]'.
phoneNumbers.value	0..1	string	The user's phone number.
phoneNumbers.display	0..1	string	A human-readable name for display purposes (READ-ONLY).
phoneNumbers.type	0..1	string	A label for the phone number's function, e.g. 'home', 'work'.
phoneNumbers.primary	0..1	boolean	Indicates if this is the primary phone number. Only one may be 'true'.
data	0..1	Object	Arbitrary user-related data.
organization	0..1	Reference	Identifies the name of an organization. Allowed references: Organization
costCenter	0..1	string	Identifies the name of a cost center.
roles	0..*	BackboneElement	A list of roles for the User that collectively represent who the User is (e.g. 'Student', 'Faculty').
roles.value	0..1	string	The value of a role.
roles.display	0..1	string	A human-readable name, primarily used for display purposes (READ-ONLY).
roles.type	0..1	string	A label indicating the attribute's function.
roles.primary	0..1	boolean	Indicates if this is the primary role. Only one may be 'true'.

Scope

Path	Card.	Type	Description
scope	1..1	string	The value of the scope
title	1..1	string	A user-friendly name for the scope that appears on the consent screen
description	0..1	string	When provided, the scope definition is additionally displayed on the consent screen

Client

Path	Card.	Type	Description
first_party	0..1	boolean	Indicates whether this is a first-party client.
auth	0..1	BackboneElement	Authentication configuration for different OAuth flows.
auth.client_credentials	0..1	BackboneElement	Configuration for the client credentials grant type.
auth.client_credentials.token_format	0..1	string	Format of the access token. Allowed values: jwt
auth.client_credentials.access_token_expiration	0..1	integer	Expiration time for access tokens in seconds.
auth.client_credentials.refresh_token_expiration	0..1	integer	Expiration time for refresh tokens in seconds.
auth.client_credentials.audience	0..*	string	Intended audience for issued tokens.
auth.client_credentials.client_assertion_types	0..*	string	Supported client assertion types. Allowed values: urn:ietf:params:oauth:client-assertion-type:jwt-bearer
auth.client_credentials.refresh_token	0..1	boolean	Whether to issue refresh tokens with this grant type.
auth.implicit	0..1	BackboneElement	Configuration for the implicit grant type.
auth.implicit.redirect_uri	0..1	url	Redirect URI for the implicit flow.
auth.implicit.token_format	0..1	string	Format of the access token. Allowed values: jwt
auth.implicit.audience	0..*	string	Intended audience for issued tokens.
auth.implicit.access_token_expiration	0..1	integer	Expiration time for access tokens in seconds.
auth.password	0..1	BackboneElement	Configuration for the password grant type.
auth.password.secret_required	0..1	boolean	Whether client secret is required for password grant.
auth.password.audience	0..*	string	Intended audience for issued tokens.
auth.password.refresh_token	0..1	boolean	Whether to issue refresh tokens with this grant type.
auth.password.redirect_uri	0..1	url	If present, turn on redirect protection
auth.password.token_format	0..1	string	Format of the access token. Allowed values: jwt
auth.password.access_token_expiration	0..1	integer	Expiration time for access tokens in seconds.
auth.password.refresh_token_expiration	0..1	integer	Expiration time for refresh tokens in seconds.
auth.authorization_code	0..1	BackboneElement	Configuration for the authorization code grant type.
auth.authorization_code.token_format	0..1	string	Format of the access token. Allowed values: jwt
auth.authorization_code.audience	0..*	string	Intended audience for issued tokens.
auth.authorization_code.secret_required	0..1	boolean	Whether client secret is required for token exchange.
auth.authorization_code.pkce	0..1	boolean	Whether PKCE (Proof Key for Code Exchange) is required.
auth.authorization_code.redirect_uri	0..1	url	Redirect URI for the authorization code flow.
auth.authorization_code.access_token_expiration	0..1	integer	Expiration time for access tokens in seconds.
auth.authorization_code.refresh_token_expiration	0..1	integer	Expiration time for refresh tokens in seconds.
auth.authorization_code.refresh_token	0..1	boolean	Whether to issue refresh tokens with this grant type.
auth.token_exchange	0..1	BackboneElement	Configuration for the token exchange grant type.
auth.token_exchange.token_format	0..1	string	Format of the access token. Allowed values: jwt
auth.token_exchange.access_token_expiration	0..1	integer	Expiration time for access tokens in seconds.
auth.token_exchange.refresh_token_expiration	0..1	integer	Expiration time for refresh tokens in seconds.
auth.token_exchange.audience	0..*	string	Intended audience for issued tokens.
auth.token_exchange.refresh_token	0..1	boolean	Whether to issue refresh tokens with this grant type.
trusted	0..1	boolean	Indicates whether this client is trusted and given special privileges.
allowed_origins	0..*	uri	Allowed Origins are URLs that will be allowed to make requests.
grant_types	0..*	string	OAuth 2.0 grant types this client is authorized to use. Allowed values: basic | authorization_code | code | password | client_credentials | implicit | refresh_token | urn:ietf:params:oauth:grant-type:token-exchange
name	0..1	string	Human-readable name of the client application.
jwks	0..*	BackboneElement	JSON Web Key Set for client authentication and/or verification.
jwks.kid	0..1	string	Key ID that identifies this key.
jwks.kty	0..1	string	Key type. Allowed values: RSA
jwks.alg	0..1	string	Algorithm used with this key. Allowed values: RS384
jwks.e	0..1	string	Exponent value for RSA key.
jwks.n	0..1	string	Modulus value for RSA key.
jwks.use	0..1	string	Key usage. Allowed values: sig
scopes	0..*	BackboneElement	Detailed scope configurations with associated policies.
scopes.policy	0..1	Reference	Reference to an AccessPolicy resource for this scope. Allowed references: AccessPolicy
scopes.parameters	0..1	Object	Parameters to be applied with the scope's policy.
fhir-base-url	0..1	string	Base URL of the FHIR server this client interacts with.
allowed-scopes	0..*	Reference	References to specific Scope resources this client is allowed to request. Allowed references: Scope
scope	0..*	string	List of scopes this client is authorized to request.
allowedIssuers	0..*	string	List of authorized token issuers for this client.
type	0..1	string	The type of client application.
secret	0..1	sha256Hash	Hashed client secret for authentication.
details	0..1	Object	Additional client details or configuration options.
active	0..1	boolean	Indicates whether this client is active and can be used for authentication.
jwks_uri	0..1	url	URI where the client's JSON Web Key Set can be retrieved.
smart	0..1	BackboneElement	SMART on FHIR configuration for this client.
smart.launch_uri	0..1	string	URI to launch the SMART app.
smart.name	0..1	string	Name of the SMART app.
smart.description	0..1	string	Description of the SMART app.
description	0..1	string	A description of the client application for administrative purposes.

Grant

Path	Card.	Type	Description
user	0..1	Reference	Reference to the user who granted the access. Allowed references: User
client	0..1	Reference	Reference to the client application being granted access. Allowed references: Client
requested-scope	0..*	string	List of scopes that were requested by the client.
provided-scope	0..*	string	List of scopes that were actually granted by the user.
patient	0..1	Reference	Reference to the patient this grant is for (in SMART on FHIR scenarios). Allowed references: Patient
scope	0..1	string	Space-separated list of granted scopes.
start	0..1	dateTime	Time when this grant was created.

Session

Path	Card.	Type	Description
on-behalf	0..1	Reference	Reference to a user on whose behalf this session is operating. Allowed references: User
parent	0..1	Reference	Reference to a parent session if this is a child session. Allowed references: Session
user	0..1	Reference	Reference to the user associated with this session. Allowed references: User
access_token	0..1	sha256Hash	Access token hash associated with this session.
refresh_token_exp	0..1	integer	Expiration time for the refresh token (in seconds since epoch).
jti	0..1	string
authorization_code	0..1	sha256Hash	Authorization code used to obtain this session.
exp	0..1	integer	Expiration time for the access token (in seconds since epoch).
start	0..1	dateTime	Time when the session started.
scope	0..*	string	List of OAuth scopes authorized for this session.
refresh_token	0..1	sha256Hash	Refresh token hash associated with this session.
type	0..1	string	Type of session (e.g., authorization_code, password, client_credentials).
patient	0..1	Reference	Reference to the patient associated with this session. Allowed references: Patient
audience	0..1	string	Intended audience for tokens issued in this session.
ctx	0..1	Object
active	0..1	boolean	Indicates whether this session is currently active.
client	0..1	Reference	Reference to the client application associated with this session. Allowed references: Client
end	0..1	dateTime	Time when the session ended or will end.

Notification

Path	Card.	Type	Description
status	0..1	string	Status of the notification delivery (delivered or error). Allowed values: delivered | error
provider	0..1	string
providerData	0..1	Object

NotificationTemplate

Path	Card.	Type	Description
subject	0..1	string	Subject line for the notification template.
template	0..1	string	Template content used to generate the notification message.

Registration

Path	Card.	Type	Description
resource	0..1	Object	Registration form data
status	0..1	string	Status of the registration process. Allowed values: activated | active
params	0..1	Object

IdentityProvider

Path	Card.	Type	Description
introspection_endpoint	0..1	string	The URL of the token introspection endpoint.
registration_endpoint	0..1	string	The URL of the registration endpoint.
team_id	0..1	string
revocation_endpoint	0..1	string	The URL of the token revocation endpoint.
authorize_endpoint	0..1	string	The URL of the authorization endpoint.
userinfo-source	0..1	string	Source of userinfo details. Allowed values: id-token | userinfo-endpoint
userinfo_header	0..1	string	Header to be used when calling the userinfo endpoint.
base_url	0..1	uri
isEmailUniqueness	0..1	boolean	Indicates whether email uniqueness should be enforced for this provider.
scopes	0..*	string	OAuth scopes that should be requested during authentication.
isScim	0..1	boolean	Indicates whether this provider supports SCIM protocol.
title	0..1	string	A human-readable name for the identity provider.
kid	0..1	string	Key identifier used for token verification.
type	0..1	string	The type of identity provider. Allowed values: aidbox | github | google | OIDC | OAuth | az-dev | yandex | okta | apple
organizations	0..*	string	Organizations associated with this identity provider.
userinfo_endpoint	0..1	string	The URL of the userinfo endpoint.
system	0..1	string	System identifier for the identity provider.
toScim	0..1	Object	Mapping rules for transforming identity provider data.
token_endpoint	0..1	string	The URL of the token endpoint.
active	0..1	boolean	Indicates whether this identity provider is active and can be used for authentication.
client	0..1	BackboneElement	Client configuration for this identity provider.
client.id	0..1	string	Client identifier used for authentication with the identity provider.
client.redirect_uri	0..1	uri	URI where the provider will redirect after authentication.
client.auth-method	0..1	string	Client authentication method. Allowed values: symmetric | asymmetric
client.secret	0..1	string	Client secret for symmetric authentication.
client.private-key	0..1	string	Private key for asymmetric authentication.
client.certificate	0..1	string	Certificate
client.certificate-thumbprint	0..1	string	Certificate thumbprint.
client.creds-ts	0..1	string
jwks_uri	0..1	string	URI where the provider's JSON Web Key Set can be retrieved.

AuthConfig

Path	Card.	Type	Description
theme	0..1	BackboneElement
theme.brand	0..1	string	Brand for auth page
theme.title	0..1	string	Title for auth page
theme.styleUrl	0..1	uri	URL to external stylesheet
theme.forgotPasswordUrl	0..1	uri	URL to forgot password page
twoFactor	0..1	BackboneElement
twoFactor.webhook	0..1	BackboneElement
twoFactor.webhook.headers	0..1	Map	Map of HTTP header key-value pairs
twoFactor.webhook.timeout	0..1	integer	Timeout in milliseconds
twoFactor.webhook.endpoint	1..1	string	URL to webhook that supports POST method
twoFactor.issuerName	0..1	string	Issuer name for OTP authenticator app
twoFactor.validPastTokensCount	0..1	integer	Number of past tokens considered valid (useful with webhook since OTP lives ~30s)
asidCookieMaxAge	0..1	integer