Multitenant Access Control - Service API - Public (1.35.0-rev2)
Download OpenAPI specification:Download
This is the public API description of Multitenant Access Control. It includes endpoints for service monitoring, access and authorization management, user and groups management, roles and resources management and application on/offboarding
OpenID Connect UserInfo Endpoint
Request user info at the OpenID UserInfo Endpoint (https://openid.net/specs/openid-connect-core-1_0.html#UserInfo).
Authorizations:
Responses
Response samples
- 200
- 400
- 401
- 403
- 500
{- "sub": "7d71dc3d-49b7-4419-86b1-7a8bb734b8de",
- "preferred_username": "admin",
- "email": "email@example.com",
- "email_verified": true,
- "roles": [
- "urn:macma-application-role:7311ea8c-5d48-43fe-acf9-980eedf24b6c:b50f1f43-33d5-4667-b4fc-65cc18fc354d:access-manager",
- "urn:macma-application-role:7311ea8c-5d48-43fe-acf9-980eedf24b6c:b50f1f43-33d5-4667-b4fc-65cc18fc354d:read-acl"
], - "tname": "bci",
- "tid": "7311ea8c-5d48-43fe-acf9-980eedf24b6c"
}
OpenID Connect UserInfo Endpoint
Request user info at the OpenID UserInfo Endpoint (https://openid.net/specs/openid-connect-core-1_0.html#UserInfo).
Authorizations:
Responses
Response samples
- 200
- 400
- 401
- 403
- 500
{- "sub": "7d71dc3d-49b7-4419-86b1-7a8bb734b8de",
- "preferred_username": "admin",
- "email": "email@example.com",
- "email_verified": true,
- "roles": [
- "urn:macma-application-role:7311ea8c-5d48-43fe-acf9-980eedf24b6c:b50f1f43-33d5-4667-b4fc-65cc18fc354d:access-manager",
- "urn:macma-application-role:7311ea8c-5d48-43fe-acf9-980eedf24b6c:b50f1f43-33d5-4667-b4fc-65cc18fc354d:read-acl"
], - "tname": "bci",
- "tid": "7311ea8c-5d48-43fe-acf9-980eedf24b6c"
}
OpenID Connect Token Introspect Endpoint
Request info about a OpenID Connect Token issued by MACMA. For further details see https://tools.ietf.org/html/rfc7662.
Authorizations:
Request Body schema: application/x-www-form-urlencodedrequired
token required | string Token issued by MACMA. |
token_type_hint | string The type of the token. |
Responses
Response samples
- 200
- 400
- 401
- 403
- 500
{- "tid": "7311ea8c-5d48-43fe-acf9-980eedf24b6c",
- "jti": "6ed999a8-3a15-4f66-8301-45f2d2df2e80",
- "active": true,
- "iat": 1565355080,
- "exp": 1565355379,
- "riexp": 1565355371,
- "nbf": 0,
- "aud": [
- "macma",
- "ppm"
], - "scope": "openid email",
- "roles": [
- "urn:macma-application-role:7311ea8c-5d48-43fe-acf9-980eedf24b6c:macma:access-manager",
- "urn:macma-application-role:7311ea8c-5d48-43fe-acf9-980eedf24b6c:macma:read-acl"
], - "azp": "string",
- "client_id": "string",
- "clientId": "string",
- "sid": "string"
}
Read the ACL (Access Control List) for all resources registered for the given application
returns the ACL of application
Authorizations:
Responses
Response samples
- 200
- 403
- 404
- 500
- 503
{- "itemCount": 1,
- "items": [
- {
- "resourceId": "4cd58843-ff9f-44e6-8408-50ba777ced23",
- "resourceType": "urn:isan:0000-0000-9E59-0000-O-0000-0000-2",
- "resourceOwningTenantId": "d523cc5a-a8d4-4341-b43b-ceda30fdffcb",
- "applicationId": "b50f1f43-33d5-4667-b4fc-65cc18fc354d",
- "grants": [
- {
- "roleName": "urn:macma-application-role:7311ea8c-5d48-43fe-acf9-980eedf24b6c:b50f1f43-33d5-4667-b4fc-65cc18fc354d:access-manager",
- "privileges": [
- "read"
]
}
]
}
]
}
Read the ACL (Access Control List) for the given user
returns the ACL of user
Authorizations:
query Parameters
includeDynamicResources | boolean Set to true if dynamic resources should be included in the User ACL response. Defaults to false if not specified. |
Responses
Response samples
- 200
- 403
- 404
- 500
- 503
{- "itemCount": 1,
- "items": [
- {
- "resourceId": "4cd58843-ff9f-44e6-8408-50ba777ced23",
- "resourceType": "urn:isan:0000-0000-9E59-0000-O-0000-0000-2",
- "resourceOwningTenantId": "d523cc5a-a8d4-4341-b43b-ceda30fdffcb",
- "applicationId": "b50f1f43-33d5-4667-b4fc-65cc18fc354d",
- "grants": [
- {
- "roleName": "urn:macma-application-role:7311ea8c-5d48-43fe-acf9-980eedf24b6c:b50f1f43-33d5-4667-b4fc-65cc18fc354d:access-manager",
- "privileges": [
- "read"
]
}
]
}
]
}
OpenID Connect Authorization Endpoint
Authenticate at the OpenID Connect Authorization Endpoint (https://openid.net/specs/openid-connect-core-1_0.html#AuthorizationEndpoint).
path Parameters
tenantId required | string <uuid> Example: 21b54338-6cf2-441b-b6b5-371f1a0a304b Id of the tenant on whose behalf you are acting ((normally) your own tenant). |
query Parameters
scope required | string The OpenID Connect scope (e.g. 'openid'). |
response_type required | string The OpenID Connect response type (e.g. 'code' for code flow). |
client_id required | string The Client ID of the application. |
redirect_uri required | string Redirection URI to which the response will be sent. |
(string or null) Method used to generate the challenge. | |
code_challenge | string Generated challenge from the code_verifier. Required when using PKCE. |
state | string Opaque value used to maintain state between the request and the callback to prevent e.g. Cross-Site Request Forgery (CSRF, XSRF). |
response_mode | string Informs the authorization server of the mechanism to be used for returning authorization response parameters from the authorization endpoint. There exists the 'query' and the 'fragment' response mode. |
Responses
Response samples
- 200
- 400
- 500
<html></html>
OpenID Connect Authorization Endpoint
Authenticate at the OpenID Connect Authorization Endpoint (https://openid.net/specs/openid-connect-core-1_0.html#AuthorizationEndpoint).
path Parameters
tenantId required | string <uuid> Example: 21b54338-6cf2-441b-b6b5-371f1a0a304b Id of the tenant on whose behalf you are acting ((normally) your own tenant). |
Request Body schema: application/x-www-form-urlencodedrequired
scope required | string The OpenID Connect scope (e.g. 'openid'). |
response_type required | string The OpenID Connect response type (e.g. 'code' for code flow). |
client_id required | string The Client ID of the application. |
redirect_uri required | string Redirection URI to which the response will be sent. |
code_challenge_method | string Enum: "plain" "S256" Method used to generate the challenge. Required when using PKCE. |
code_challenge | string Generated challenge from the code_verifier. Required when using PKCE. |
state | string Opaque value used to maintain state between the request and the callback to prevent e.g. Cross-Site Request Forgery (CSRF, XSRF). |
response_mode | string Informs the authorization server of the mechanism to be used for returning authorization response parameters from the authorization endpoint. There exists the 'query' and the 'fragment' response mode. |
Responses
Response samples
- 400
- 500
{- "error": {
- "message": "Invalid content. Object has missing required properties ([{property1},{property2}])"
}
}
OpenID Connect Discovery Endpoint.
Obtaining OpenID Provider Configuration Information. Refer to https://openid.net/specs/openid-connect-discovery-1_0.html#ProviderConfig for more detailed information.
path Parameters
tenantId required | string <uuid> Example: 21b54338-6cf2-441b-b6b5-371f1a0a304b Id of the tenant on whose behalf you are acting ((normally) your own tenant). |
Responses
OpenID Connect Token Endpoint
Request OAuth2 Access and Refresh Tokens. For end user authentication (authorization code grant flow) see https://openid.net/specs/openid-connect-core-1_0.html#TokenEndpoint. For application authentication (client credentials grant flow) see https://tools.ietf.org/html/rfc6749#section-4.4. Authorization code flow with public client does not require any authentication, other use cases have stricter requirements as defined in the RFCs.
path Parameters
tenantId required | string <uuid> Example: 21b54338-6cf2-441b-b6b5-371f1a0a304b Id of the tenant on whose behalf you are acting ((normally) your own tenant). |
Request Body schema: application/x-www-form-urlencodedrequired
grant_type required | string Denotes the flow which shall be used. For Authorization Code Grant with PKCE (RFC 7636) use authorization_code. |
client_id required | string The client id to login. |
client_secret | string The secret of a client. If the client was issued a client secret, then the server must authenticate the client. |
code_verifier | string The code verifier for the PKCE request, that the app originally generated before the authorization request. Required when using PKCE. |
code required | string The authorization code received from the authorization endpoint. Required when using PKCE. |
redirect_uri required | string The redirect uri which was sent with the authorization endpoint request. |
Responses
Response samples
- 200
- 400
- 500
{- "access_token": "eyJhbGciOiJSUzI1N....8E5-I8501wgWA9H5xcb9YvLQ",
- "expires_in": 300,
- "refresh_expires_in": 1800,
- "token_type": "bearer",
- "scope": "tenant email profile macma_permissions",
- "refresh_token": "eyJhbGciOiJIUzI....eXrCfAW8BA4cObM7aBVR7A"
}
Read applications
Returns a list of all available applications
Authorizations:
path Parameters
tenantId required | string <uuid> Example: 21b54338-6cf2-441b-b6b5-371f1a0a304b Id of the tenant on whose behalf you are acting ((normally) your own tenant). |
query Parameters
start | integer Example: start=0 Starting page index which is starting by 0 (default 0). |
count | integer Example: count=100 Number of items to return per call (pageSize, default 100). |
search | string A String contained in the id, name or description. |
Responses
Response samples
- 200
- 403
- 404
- 500
- 503
{- "itemCount": 1,
- "currentPage": 0,
- "pageSize": 10,
- "items": [
- {
- "id": "1qjbd49azhwxs1o15h9bg87wn2",
- "name": "webapp",
- "displayName": "Nice name",
- "owningTenantId": "c6751e19-86d1-4f64-82e2-0e2f10f3d56a",
- "owningTenantName": "Example Inc.",
- "includesPublicClient": true,
- "enableUserLoginWithConfidentialClient": true,
- "webOriginOrRedirectUriMismatch": false,
- "clientId": "1qjbd49azhwxs1o15h9bg87wn2",
- "publicClientId": "1qjbd49azhwxs1o15h9bg87wn2-frontend",
- "errors": [
- "Confidential client 6yncginm71r81ixvkmveoyeay for application MyApp does not exist in keycloak."
]
}
]
}
Register an application
Register an application in a software provider tenant, receiving clientIDs and credentials in return.
Authorizations:
path Parameters
tenantId required | string <uuid> Example: 21b54338-6cf2-441b-b6b5-371f1a0a304b Id of the tenant on whose behalf you are acting ((normally) your own tenant). |
Request Body schema: application/jsonrequired
name required | string <= 255 characters ^[a-zA-Z0-9\-_+=()\[\]#.@&%!',;$]+([ ]+[a-zA-... |
displayName | string <= 255 characters ^[a-zA-Z0-9ßüöäÜÖÄ\-_+=()\[\]#.@&%!',;$]+([ ]... |
clientSecret | string <= 200 characters ^[a-zA-Z0-9\-_=()\[\]#.@&!:,;'$?/*]+([ ]+[a-z... Client credential's secret for OAuth flows of the backend. It must not be used in public clients like desktop, mobile or browser application. |
includesPublicClient | boolean Default: false If a public client is required (for browser, mobile or desktop applications using login independent of its backend). It is only possible to include a public client if the user login is enabled with the confidential client. |
enableUserLoginWithConfidentialClient | boolean Default: false Enables Authorization Code Grant with confidential client. If includesPublicClient is true enableUserLoginWithConfidentialClient is automatically enabled. |
redirectUris | Array of strings Valid URLs to redirect to after SSO login. May end with * as wildcard. |
webOrigins | Array of strings Allowed web origins for cross origin resource sharing (CORS). Must match scheme://hostname[:port] |
Responses
Request samples
- Payload
{- "name": "My App",
- "displayName": "My App nice name",
- "clientSecret": "2k3fj3aseghhjllaojew4tj",
- "includesPublicClient": true,
- "enableUserLoginWithConfidentialClient": true,
}
Response samples
- 201
- 400
- 403
- 404
- 409
- 500
- 503
{- "id": "1qjbd49azhwxs1o15h9bg87wn2",
- "name": "webapp",
- "displayName": "My App nice name",
- "description": "This is the MACMA Webapp.",
- "owningTenantId": "c6751e19-86d1-4f64-82e2-0e2f10f3d56a",
- "owningTenantName": "Example Inc.",
- "includesPublicClient": true,
- "enableUserLoginWithConfidentialClient": true,
- "clientId": "1qjbd49azhwxs1o15h9bg87wn2",
- "clientSecret": "2k3fj3aseghhjllaojew4tj",
- "publicClientId": "1qjbd49azhwxs1o15h9bg87wn2-frontend",
}
Read application
Returns information about a certain application
Authorizations:
path Parameters
tenantId required | string <uuid> Example: 21b54338-6cf2-441b-b6b5-371f1a0a304b Id of the tenant on whose behalf you are acting ((normally) your own tenant). |
applicationId required | string Example: wt94fzxtthnwz2km63qduude Id of the application. |
Responses
Response samples
- 200
- 403
- 404
- 500
- 503
{- "id": "1qjbd49azhwxs1o15h9bg87wn2",
- "name": "webapp",
- "displayName": "Nice name",
- "owningTenantId": "c6751e19-86d1-4f64-82e2-0e2f10f3d56a",
- "owningTenantName": "Example Inc.",
- "includesPublicClient": true,
- "enableUserLoginWithConfidentialClient": true,
- "webOriginOrRedirectUriMismatch": false,
- "clientId": "1qjbd49azhwxs1o15h9bg87wn2",
- "publicClientId": "1qjbd49azhwxs1o15h9bg87wn2-frontend",
- "errors": [
- "Confidential client 6yncginm71r81ixvkmveoyeay for application MyApp does not exist in keycloak."
]
}
Update application
Update information about a certain application
Authorizations:
path Parameters
tenantId required | string <uuid> Example: 21b54338-6cf2-441b-b6b5-371f1a0a304b Id of the tenant on whose behalf you are acting ((normally) your own tenant). |
applicationId required | string Example: wt94fzxtthnwz2km63qduude Id of the application. |
Request Body schema: application/jsonrequired
name required | string <= 255 characters ^[a-zA-Z0-9\-_+=()\[\]#.@&%!',;$]+([ ]+[a-zA-... |
displayName | string <= 255 characters ^[a-zA-Z0-9ßüöäÜÖÄ\-_+=()\[\]#.@&%!',;$]+([ ]... |
includesPublicClient required | boolean Default: false If a public client is required (for browser, mobile or desktop applications using login independent of its backend). It is only possible to include a public client if the user login is enabled with the confidential client. |
enableUserLoginWithConfidentialClient required | boolean Default: false Enables Authorization Code Grant with confidential client. If includesPublicClient is true enableUserLoginWithConfidentialClient is automatically enabled. |
redirectUris | Array of strings <uri> [ items <uri > ] Valid URLs to redirect to after SSO login. May end with * as wildcard. |
webOrigins | Array of strings <uri> [ items <uri > ] Allowed web origins for cross origin resource sharing (CORS). Must match scheme://hostname[:port] |
Responses
Request samples
- Payload
{- "name": "My App",
- "displayName": "My App nice name",
- "includesPublicClient": true,
- "enableUserLoginWithConfidentialClient": true,
}
Response samples
- 200
- 400
- 403
- 404
- 500
- 503
{- "id": "1qjbd49azhwxs1o15h9bg87wn2",
- "name": "webapp",
- "displayName": "Nice name",
- "owningTenantId": "c6751e19-86d1-4f64-82e2-0e2f10f3d56a",
- "owningTenantName": "Example Inc.",
- "includesPublicClient": true,
- "enableUserLoginWithConfidentialClient": true,
- "webOriginOrRedirectUriMismatch": false,
- "clientId": "1qjbd49azhwxs1o15h9bg87wn2",
- "publicClientId": "1qjbd49azhwxs1o15h9bg87wn2-frontend",
- "errors": [
- "Confidential client 6yncginm71r81ixvkmveoyeay for application MyApp does not exist in keycloak."
]
}
Delete an application that is not shared.
Trying to delete an application that is still shared will return 422 (Unprocessable Entity).
Authorizations:
path Parameters
tenantId required | string <uuid> Example: 21b54338-6cf2-441b-b6b5-371f1a0a304b Id of the tenant on whose behalf you are acting ((normally) your own tenant). |
applicationId required | string Id of the application to be deleted. |
Responses
Response samples
- 400
- 403
- 404
- 422
- 500
- 503
{- "error": {
- "message": "Invalid content. Object has missing required properties ([{property1},{property2}])"
}
}
Change client secret.
WARNING
It is not sufficient to change the client secret by this endpoint. It is crucial to adapt the application configuration accordingly with the new secret. Otherwise the modules will not be able to login anymore.
Authorizations:
path Parameters
tenantId required | string <uuid> Example: 21b54338-6cf2-441b-b6b5-371f1a0a304b Id of the tenant on whose behalf you are acting ((normally) your own tenant). |
applicationId required | string Example: wt94fzxtthnwz2km63qduude Id of the application. |
Request Body schema: application/jsonrequired
clientSecret required | string <= 200 characters ^[a-zA-Z0-9\-_=()\[\]#.@&!:,;'$?/*]+([ ]+[a-z... Client credential's secret for OAuth flows of the backend. It must not be used in public clients like desktop, mobile or browser application. |
Responses
Request samples
- Payload
{- "clientSecret": "2k3fj3aseghhjllaojew4tj"
}
Response samples
- 400
- 403
- 404
- 500
{- "error": {
- "message": "Invalid content. Object has missing required properties ([{property1},{property2}])"
}
}
Read application and tenant roles assigned to an application
Returns the list of roles assigned to an application
Authorizations:
path Parameters
tenantId required | string <uuid> Example: 21b54338-6cf2-441b-b6b5-371f1a0a304b Id of the tenant on whose behalf you are acting ((normally) your own tenant). |
applicationId required | string Example: wt94fzxtthnwz2km63qduude Id of the application. |
query Parameters
start | integer Example: start=0 Starting page index which is starting by 0 (default 0). |
count | integer Example: count=100 Number of items to return per call (pageSize, default 100). |
search | string A String contained in role name, display name or description. |
Responses
Response samples
- 200
- 400
- 403
- 404
- 500
- 503
{- "currentPage": 0,
- "pageSize": 10,
- "itemCount": 1,
- "items": [
- {
- "id": "urn:macma-application-role:7311ea8c-5d48-43fe-acf9-980eedf24b6c:b50f1f43-33d5-4667-b4fc-65cc18fc354d:iot-developer",
- "applicationId": "b50f1f43-33d5-4667-b4fc-65cc18fc354d",
- "name": "iot-developer",
- "displayName": "IoT Developer",
- "description": "has advanced access",
- "type": "macma-application-role",
- "owningTenantId": "7311ea8c-5d48-43fe-acf9-980eedf24b6c",
- "owningTenantName": "Example Inc"
}
]
}
Assign a role to an application
Assign a role to an application, thus granting it permissions.
Authorizations:
path Parameters
tenantId required | string <uuid> Example: 21b54338-6cf2-441b-b6b5-371f1a0a304b Id of the tenant on whose behalf you are acting ((normally) your own tenant). |
applicationId required | string Example: wt94fzxtthnwz2km63qduude Id of the application. |
roleId required | string Examples:
Id of the role. |
Responses
Response samples
- 400
- 403
- 404
- 422
- 500
- 503
{- "error": {
- "message": "Invalid content. Object has missing required properties ([{property1},{property2}])"
}
}
Unassign a role from an application
Unassign a role from an application, thus withdraw permissions from it.
Authorizations:
path Parameters
tenantId required | string <uuid> Example: 21b54338-6cf2-441b-b6b5-371f1a0a304b Id of the tenant on whose behalf you are acting ((normally) your own tenant). |
applicationId required | string Example: wt94fzxtthnwz2km63qduude Id of the application. |
roleId required | string Examples:
Id of the role. |
Responses
Response samples
- 400
- 403
- 404
- 422
- 500
- 503
{- "error": {
- "message": "Invalid content. Object has missing required properties ([{property1},{property2}])"
}
}
Create or update application roles
This endpoint is used to register new and update existing application roles and their permissions. When creating application roles, MACMA does not provide ids. E.g. ids from the body payload are just representation of the ids within the application. Therefore, uniqueness of application roles in MACMA is established by combining tenantId (path-parameter), applicationId (path-parameter), name (payload). Each array element represents a single application role so that it's possible to register multiple application roles and their permissions.
Authorizations:
path Parameters
tenantId required | string <uuid> Example: 21b54338-6cf2-441b-b6b5-371f1a0a304b Id of the tenant on whose behalf you are acting ((normally) your own tenant). |
applicationId required | string Id of the application managing the application role. |
Request Body schema: application/jsonrequired
Array of objects (ApplicationRole) [ 1 .. 100 ] items |
Responses
Request samples
- Payload
{- "items": [
- {
- "name": "developer",
- "displayName": "IoT Developer",
- "description": "has advanced access",
- "permissions": [
- {
- "resourceId": "4cd58843-ff9f-44e6-8408-50ba777ced23",
- "resourceType": "urn:isan:0000-0000-9E59-0000-O-0000-0000-2",
- "privileges": [
- "read",
- "modify"
]
}
]
}
]
}
Response samples
- 200
- 207
- 400
- 403
- 404
- 422
- 500
- 503
{- "responses": [
- {
- "status": 200
}, - {
- "status": 200
}
]
}
Delete application roles
This endpoint is used to delete application roles and their permissions. Each array element represents a single application role so that it's possible to delete multiple application roles with their permissions.
Authorizations:
path Parameters
tenantId required | string <uuid> Example: 21b54338-6cf2-441b-b6b5-371f1a0a304b Id of the tenant on whose behalf you are acting ((normally) your own tenant). |
applicationId required | string Example: wt94fzxtthnwz2km63qduude Id of the application. |
Request Body schema: application/jsonrequired
required | Array of objects (ApplicationRoleDeletion) [ 1 .. 100 ] items |
Responses
Request samples
- Payload
{- "items": [
- {
- "name": "iot-developer"
}
]
}
Response samples
- 200
- 207
- 400
- 403
- 404
- 422
- 500
- 503
{- "responses": [
- {
- "status": 200
}, - {
- "status": 200
}
]
}
Add application role to an user
Authorizations:
path Parameters
tenantId required | string <uuid> Example: 21b54338-6cf2-441b-b6b5-371f1a0a304b Id of the tenant on whose behalf you are acting ((normally) your own tenant). |
applicationId required | string Example: wt94fzxtthnwz2km63qduude Id of the application. |
applicationRoleId required | string Example: urn:macma-application-role:28b0e854-d67c-408e-a9af-ae1bca75db5c:macma:identity-provider-manager Id of an application role. |
userId required | string <uuid> Example: 1022bc8e-9df7-4703-bd01-a160cffc6bdb Id of the user. |
Responses
Response samples
- 400
- 403
- 404
- 500
- 503
{- "error": {
- "message": "Invalid content. Object has missing required properties ([{property1},{property2}])"
}
}
Remove user from an application role
Authorizations:
path Parameters
tenantId required | string <uuid> Example: 21b54338-6cf2-441b-b6b5-371f1a0a304b Id of the tenant on whose behalf you are acting ((normally) your own tenant). |
applicationId required | string Example: wt94fzxtthnwz2km63qduude Id of the application. |
applicationRoleId required | string Example: urn:macma-application-role:28b0e854-d67c-408e-a9af-ae1bca75db5c:macma:identity-provider-manager Id of an application role. |
userId required | string <uuid> Example: 1022bc8e-9df7-4703-bd01-a160cffc6bdb Id of the user. |
Responses
Response samples
- 400
- 403
- 404
- 500
- 503
{- "error": {
- "message": "Invalid content. Object has missing required properties ([{property1},{property2}])"
}
}
Add application role to a group
Authorizations:
path Parameters
tenantId required | string <uuid> Example: 21b54338-6cf2-441b-b6b5-371f1a0a304b Id of the tenant on whose behalf you are acting ((normally) your own tenant). |
applicationId required | string Example: wt94fzxtthnwz2km63qduude Id of the application. |
applicationRoleId required | string Example: urn:macma-application-role:28b0e854-d67c-408e-a9af-ae1bca75db5c:macma:identity-provider-manager Id of an application role. |
groupId required | string <uuid> Example: 7b7a96f2-3098-4a71-bb77-27423da6331b Id of the group. |
Responses
Response samples
- 400
- 403
- 404
- 500
- 503
{- "error": {
- "message": "Invalid content. Object has missing required properties ([{property1},{property2}])"
}
}
Remove group from an application role
Authorizations:
path Parameters
tenantId required | string <uuid> Example: 21b54338-6cf2-441b-b6b5-371f1a0a304b Id of the tenant on whose behalf you are acting ((normally) your own tenant). |
applicationId required | string Example: wt94fzxtthnwz2km63qduude Id of the application. |
applicationRoleId required | string Example: urn:macma-application-role:28b0e854-d67c-408e-a9af-ae1bca75db5c:macma:identity-provider-manager Id of an application role. |
groupId required | string <uuid> Example: 7b7a96f2-3098-4a71-bb77-27423da6331b Id of the group. |
Responses
Response samples
- 400
- 403
- 404
- 500
- 503
{- "error": {
- "message": "Invalid content. Object has missing required properties ([{property1},{property2}])"
}
}
Create a contract
Authorizations:
path Parameters
tenantId required | string <uuid> Example: 21b54338-6cf2-441b-b6b5-371f1a0a304b Id of the tenant on whose behalf you are acting ((normally) your own tenant). |
Request Body schema: application/jsonrequired
consumingTenantId | string <uuid> The tenant which acts as the contract consumer. |
name required | string Name of contract that is unique for two contractual parties. |
description | string Description of contract, may be empty. |
username | string An optional username that all roles of this contract will be assigned to. Failure of assignment will not be reported. |
applicableScope | string Default: "CONSUMER" Enum: "PROVIDER" "CONSUMER" Whether the contract will give access to the provider's or consumer's resources. |
Array of objects (ContractRoleCreation) The roles which are the contractual basis. |
Responses
Request samples
- Payload
{- "consumingTenantId": "3d2981a8-4774-43ce-a08c-04596f720e48",
- "name": "FizzBuzz",
- "description": "This is a wonderful fizzbuzz",
- "username": "johnDoe42",
- "applicableScope": "CONSUMER",
- "roles": [
- {
- "name": "access-manager",
- "applicationId": "macma"
}
]
}
Response samples
- 201
- 400
- 403
- 409
- 500
- 503
{- "id": "58be984c-da35-4b92-85ae-da5ee3c5631e"
}
Get dynamic resources belonging to the given tenant and application
Returns dynamic resources belonging to the given tenant and application, IFF the caller is the application itself.
Authorizations:
path Parameters
tenantId required | string <uuid> Example: 21b54338-6cf2-441b-b6b5-371f1a0a304b Id of the tenant on whose behalf you are acting ((normally) your own tenant). |
applicationId required | string Id of the application managing the resource. |
Responses
Response samples
- 200
- 400
- 403
- 404
- 500
- 503
{- "currentPage": 0,
- "itemCount": 0,
- "totalItems": 0,
- "totalPages": 0,
- "items": [
- {
- "id": "dafdd949-80c3-459a-b94c-5d6398840e07",
- "name": "Machine 123",
- "type": "urn:isan:0000-0000-9E59-0000-O-0000-0000-2",
- "isDynamic": "false",
- "description": "The machine used to create part x",
- "privileges": [
- "read",
- "modify"
], - "owningTenantId": "d523cc5a-a8d4-4341-b43b-ceda30fdffcb",
- "owningTenantName": "Example Inc"
}
]
}
Create dynamic resources
This endpoint is used to register new dynamic resources. When creating new dynamic resources, MACMA does not provide ids. E.g. ids from the body payload are just representation of the ids within the application. Therefore, uniqueness of dynamic resources in MACMA is established by combining tenantId (path-parameter), applicationId (path-parameter), id (payload) and the type (payload). Each array element represents a single resource so that it is possible to register multiple resources.
When using the endpoint consider the following limitations:
- The BearerToken used for calling this endpoint needs to be valid for the tenant where the dynamic resources will be created
- Max 100 dynamic resources per request allowed
- Dynamic resources can only be assigned to tenant roles
- Dynamic resources can only be created by the own application
- Resources need to have at least one privilege
- The resource id, type and name are case sensitive
- Bulk failure mode is undefined: the implementation may either create as many resources as possible or none at all if any of them fails - do not depend on this. Only the result code(s) will specify what has been done
Authorizations:
path Parameters
tenantId required | string <uuid> Example: 21b54338-6cf2-441b-b6b5-371f1a0a304b Id of the tenant on whose behalf you are acting ((normally) your own tenant). |
applicationId required | string Id of the application managing the resource. |
Request Body schema: application/jsonrequired
Array of objects (ResourceCreate) [ 1 .. 100 ] items |
Responses
Request samples
- Payload
{- "items": [
- {
- "id": "4cd58843-ff9f-44e6-8408-50ba777ced23",
- "name": "Machine 123",
- "type": "urn:isan:0000-0000-9E59-0000-O-0000-0000-2",
- "description": "The machine used to create part x",
- "privileges": [
- "read",
- "modify"
]
}
]
}
Response samples
- 201
- 207
- 400
- 403
- 404
- 409
- 500
- 503
{- "responses": [
- {
- "status": 201
}, - {
- "status": 201
}
]
}
Update dynamic resources
This endpoint is used to update dynamic resources.
When using the endpoint consider the following limitations:
- The BearerToken used for calling this endpoint needs to be valid for the tenant where the dynamic resources will be updated
- Max 100 dynamic resources per request allowed
- Resources need to have at least one privilege
- The resource id, type and name are case sensitive
- Dynamic resources can only be updated by the own application
- Bulk failure mode is undefined: the implementation may either update as many resources as possible or none at all if any of them fails - do not depend on this. Only the result code(s) will specify what has been done
Authorizations:
path Parameters
tenantId required | string <uuid> Example: 21b54338-6cf2-441b-b6b5-371f1a0a304b Id of the tenant on whose behalf you are acting ((normally) your own tenant). |
applicationId required | string Id of the application managing the resource. |
Request Body schema: application/jsonrequired
Array of objects (ResourceCreate) [ 1 .. 100 ] items |
Responses
Request samples
- Payload
{- "items": [
- {
- "id": "4cd58843-ff9f-44e6-8408-50ba777ced23",
- "name": "Machine 123",
- "type": "urn:isan:0000-0000-9E59-0000-O-0000-0000-2",
- "description": "The machine used to create part x",
- "privileges": [
- "read",
- "modify"
]
}
]
}
Response samples
- 200
- 207
- 400
- 403
- 404
- 500
- 503
{- "responses": [
- {
- "status": 200
}, - {
- "status": 200
}
]
}
Delete dynamic resources
This endpoint is used to delete dynamic resources. Each array element represents a single dynamic resource so that it is possible to delete multiple dynamic resources.
When using the endpoint consider the following limitations:
- The BearerToken used for calling this endpoint needs to be valid for the tenant where the dynamic resources will be deleted
- Max 100 dynamic resources per request allowed
- Dynamic resources can only be deleted by the own application
- The resource id, type and name are case sensitive
- Bulk failure mode is undefined: the implementation may either delete as many resources as possible or none at all if any of them fails - do not depend on this. Only the result code(s) will specify what has been done
Authorizations:
path Parameters
tenantId required | string <uuid> Example: 21b54338-6cf2-441b-b6b5-371f1a0a304b Id of the tenant on whose behalf you are acting ((normally) your own tenant). |
applicationId required | string Id of the application managing the resource. |
Request Body schema: application/jsonrequired
required | Array of objects (ResourceDeletion) [ 1 .. 100 ] items |
Responses
Request samples
- Payload
{- "items": [
- {
- "id": "4cd58843-ff9f-44e6-8408-50ba777ced23",
- "type": "urn:isan:0000-0000-9E59-0000-O-0000-0000-2"
}
]
}
Response samples
- 200
- 207
- 400
- 403
- 404
- 500
- 503
{- "responses": [
- {
- "status": 200
}, - {
- "status": 200
}
]
}
Return the application's current health status
Returns the application's current health status.
header Parameters
com.bosch.correlationId | string Header for correlation of related requests. |
Accept | string Example: application/json Header for accepted MIME type. |
Responses
Response samples
- 200
{- "name": "Multitenant Access Control - Webapp - Backend",
- "description": "Multitenant Access Control Webapp Backend implementation that also aggregates Frontend.",
- "instanceId": "instance-id",
- "startupTime": "2022-09-27T12:53:09.1546536+00:00",
- "version": "1.20.0",
- "ready": true,
- "health": "HEALTHY",
- "onStateSince": "2022-09-27:14:30:58",
- "details": { },
- "dependencies": [
- {
- "name": "Core",
- "description": "Service for tenant authorization including data sharing.",
- "available": true,
- "details": { }
}
]
}
Response samples
- 200
- 403
{- "info": {
- "id": "macma",
- "authProviderClientId": "macma",
- "name": "Multitenant Access Control",
- "vendor": "BCI",
- "version": "1.20.0-2024-04-05T05:54:03.251Z",
- "supportedLanguages": [
- "en",
- "de"
]
}, - "views": {
- "items": [
- {
- "title": "/users?tenant=##tenantId##",
- "resourceId": "$all.users",
- "resourceType": "urn:com:bosch:bci:macma:entity:users",
- "navigationPriority": 1,
- "navigationPath": [
- "user-management",
- "users"
], - "navigationRoute": "/#/users",
- "localization": { },
- "htmlFile": "/users?tenant=##tenantId##"
}
]
}, - "documents": {
- "items": [
- {
- "title": "API Documentation",
- "resourceId": "$all.public-documents",
- "resourceType": "urn:com:bosch:bci:macma:entity:public-documents",
- "type": "api-documentation",
- "format": "html",
- "url": "doc/api/public-api.yaml",
- "language": "en"
}
]
}
}
List all available tenant- and application-roles
Authorizations:
path Parameters
tenantId required | string <uuid> Example: 21b54338-6cf2-441b-b6b5-371f1a0a304b Id of the tenant on whose behalf you are acting ((normally) your own tenant). |
query Parameters
start | integer Example: start=0 Starting page index which is starting by 0 (default 0). |
count | integer Example: count=100 Number of items to return per call (pageSize, default 100). |
type | string Enum: "application" "tenant" Type of roles to return. |
search | string A String contained in role name, display name or description |
Responses
Response samples
- 200
- 400
- 403
- 500
- 503
{- "currentPage": 0,
- "pageSize": 10,
- "itemCount": 2,
- "items": [
- {
- "id": "urn:macma-tenant-role:7311ea8c-5d48-43fe-acf9-980eedf24b6c:iot-developer",
- "name": "iot-developer",
- "displayName": "IoT Developer",
- "description": "has advanced access",
- "type": "macma-tenant-role",
- "owningTenantId": "7311ea8c-5d48-43fe-acf9-980eedf24b6c",
- "owningTenantName": "Example Inc"
}
]
}
Get all static resources of the specified application of its owning tenant
Returns only static resources in the given tenant IFF the caller is the application itself AND the given tenant is the software providing tenant of that application
Authorizations:
path Parameters
tenantId required | string <uuid> Example: 21b54338-6cf2-441b-b6b5-371f1a0a304b Id of the tenant on whose behalf you are acting ((normally) your own tenant). |
applicationId required | string Id of the application managing the resource. |
Responses
Response samples
- 200
- 400
- 403
- 404
- 500
- 503
{- "currentPage": 0,
- "itemCount": 0,
- "totalItems": 0,
- "totalPages": 0,
- "items": [
- {
- "id": "dafdd949-80c3-459a-b94c-5d6398840e07",
- "name": "Machine 123",
- "type": "urn:isan:0000-0000-9E59-0000-O-0000-0000-2",
- "isDynamic": "false",
- "description": "The machine used to create part x",
- "privileges": [
- "read",
- "modify"
], - "owningTenantId": "d523cc5a-a8d4-4341-b43b-ceda30fdffcb",
- "owningTenantName": "Example Inc"
}
]
}
Create or update static resources
This endpoint is used to register new and update existing static resources. When creating static resources, MACMA does not provide ids. E.g. ids from the body payload are just representation of the ids within the application. Therefore, uniqueness of resources in MACMA is established by combining tenantId (path-parameter), applicationId (path-parameter), id (payload) and the type (payload). Each array element represents a single resource so that it's possible to register multiple resources. When using the endpoint consider the following limitations:
- The BearerToken used for calling this endpoint needs to be valid for the software providing tenant
- Max 100 resources per request allowed
- The request fails if one of the resources already exists
- The request fails if one of the resource ids is equal (case insensitive) to an id of an existing resource of the same type
- The request fails if one of the resource types equals the type of a dynamic resource
- As there is no rollback implemented the caller is responsible for the cleanup
- Resources need to have at least one privilege
Authorizations:
path Parameters
tenantId required | string <uuid> Example: 21b54338-6cf2-441b-b6b5-371f1a0a304b Id of the tenant on whose behalf you are acting ((normally) your own tenant). |
applicationId required | string Id of the application managing the resource. |
Request Body schema: application/jsonrequired
Array of objects (ResourceCreate) [ 1 .. 100 ] items |
Responses
Request samples
- Payload
{- "items": [
- {
- "id": "4cd58843-ff9f-44e6-8408-50ba777ced23",
- "name": "Machine 123",
- "type": "urn:isan:0000-0000-9E59-0000-O-0000-0000-2",
- "description": "The machine used to create part x",
- "privileges": [
- "read",
- "modify"
]
}
]
}
Response samples
- 200
- 207
- 400
- 403
- 404
- 422
- 500
- 503
{- "responses": [
- {
- "status": 200
}, - {
- "status": 200
}
]
}
Delete static resources
This endpoint is used to delete static resources. Each array element represents a single static resource so that it's possible to delete multiple application roles. The ids from the body payload are just representation of the ids within the application.
Authorizations:
path Parameters
tenantId required | string <uuid> Example: 21b54338-6cf2-441b-b6b5-371f1a0a304b Id of the tenant on whose behalf you are acting ((normally) your own tenant). |
applicationId required | string Id of the application managing the resource. |
Request Body schema: application/jsonrequired
required | Array of objects (ResourceDeletion) [ 1 .. 100 ] items |
Responses
Request samples
- Payload
{- "items": [
- {
- "id": "4cd58843-ff9f-44e6-8408-50ba777ced23",
- "type": "urn:isan:0000-0000-9E59-0000-O-0000-0000-2"
}
]
}
Response samples
- 200
- 207
- 400
- 403
- 404
- 422
- 500
- 503
{- "responses": [
- {
- "status": 200
}, - {
- "status": 200
}
]
}
Read all tenants, to whom the current tenant has a relation. Pagination is currently not supported, all items will be returned.
reads all tenant list
Authorizations:
path Parameters
tenantId required | string <uuid> Example: 21b54338-6cf2-441b-b6b5-371f1a0a304b Id of the tenant on whose behalf you are acting ((normally) your own tenant). |
query Parameters
checkOutgoingContracts | boolean Default: false Whether to check for outgoing contracts. |
Responses
Response samples
- 200
- 400
- 403
- 404
- 500
- 503
{- "itemCount": 1,
- "currentPage": 0,
- "pageSize": 1000,
- "totalItems": 1,
- "totalPages": 1,
- "items": [
- {
- "id": "58be984c-da35-4b92-85ae-da5ee3c5631e",
- "name": "ACMECorp",
- "createdByTenantId": "7311ea8c-5d48-43fe-acf9-980eedf24b6c",
- "createdForTenantId": "7311ea8c-5d48-43fe-acf9-980eedf24b6c",
- "hasOutgoingContracts": true
}
]
}
Create tenant
This endpoint is used to create a new tenant with an admin user. The credentials of the admin user have to be specified via "username" and "password". The password requires at least ten characters including one digit, one lower case letter, one capital letter and one special character. It is temporary and has to be changed on first login. The id (uuid) for the tenant can be passed. If not present, a random one is generated. Ids must be unique and never have been used before (including deleted tenants).
Authorizations:
path Parameters
tenantId required | string <uuid> Example: 21b54338-6cf2-441b-b6b5-371f1a0a304b Id of the tenant on whose behalf you are acting ((normally) your own tenant). |
Request Body schema: application/jsonrequired
id | string <uuid> id of the created tenant - request will fail if this has been used previously |
name required | string |
username required | string |
password required | string |
Responses
Request samples
- Payload
{- "id": "e6ff3a22-db32-42e4-8f2f-0866f620971c",
- "name": "ACMECorp",
- "username": "admin",
- "password": "xQ9BvToq.F1HyR!!!"
}
Response samples
- 201
- 400
- 403
- 409
- 500
- 503
{- "id": "58be984c-da35-4b92-85ae-da5ee3c5631e",
- "name": "ACMECorp",
- "createdByTenantId": "7311ea8c-5d48-43fe-acf9-980eedf24b6c",
- "createdForTenantId": "7311ea8c-5d48-43fe-acf9-980eedf24b6c",
- "hasOutgoingContracts": true
}
Delete a tenant
Authorizations:
path Parameters
tenantId required | string <uuid> Example: 21b54338-6cf2-441b-b6b5-371f1a0a304b Id of the tenant on whose behalf you are acting ((normally) your own tenant). |
tenantToDeleteId required | string Id of the tenant to be deleted. |
Responses
Response samples
- 400
- 403
- 404
- 422
- 500
- 503
{- "error": {
- "message": "Invalid content. Object has missing required properties ([{property1},{property2}])"
}
}
Create tenant role
Authorizations:
path Parameters
tenantId required | string <uuid> Example: 21b54338-6cf2-441b-b6b5-371f1a0a304b Id of the tenant on whose behalf you are acting ((normally) your own tenant). |
Request Body schema: application/jsonrequired
name required | string <= 200 characters ^[a-zA-Z0-9_\-]+$ The technical name of the role (e.g. for authorization). |
displayName required | string <= 255 characters The display name of the role (e.g. for UI). |
description | string <= 255 characters An additional description which explains e.g. the purpose of the role. |
Array of objects (TenantRolePrivileges) |
Responses
Request samples
- Payload
{- "name": "iot-developer",
- "displayName": "IoT Developer",
- "description": "has advanced access",
- "permissions": [
- {
- "owningTenantId": "d523cc5a-a8d4-4341-b43b-ceda30fdffcb",
- "applicationId": "b50f1f43-33d5-4667-b4fc-65cc18fc354d",
- "resourceId": "4cd58843-ff9f-44e6-8408-50ba777ced23",
- "resourceType": "urn:isan:0000-0000-9E59-0000-O-0000-0000-2",
- "privileges": [
- "read",
- "modify"
]
}
]
}
Response samples
- 201
- 400
- 403
- 404
- 409
- 422
- 500
- 503
{- "id": "urn:macma-tenant-role:7311ea8c-5d48-43fe-acf9-980eedf24b6c:iot-developer",
- "name": "iot-developer",
- "displayName": "IoT Developer",
- "description": "has advanced access",
- "type": "macma-tenant-role",
- "owningTenantId": "7311ea8c-5d48-43fe-acf9-980eedf24b6c",
- "owningTenantName": "Example Inc",
- "permissions": [
- {
- "owningTenantId": "d523cc5a-a8d4-4341-b43b-ceda30fdffcb",
- "owningTenantName": "Example Inc",
- "applicationId": "b50f1f43-33d5-4667-b4fc-65cc18fc354d",
- "resourceId": "4cd58843-ff9f-44e6-8408-50ba777ced23",
- "resourceType": "urn:isan:0000-0000-9E59-0000-O-0000-0000-2",
- "isDynamicResource": "false",
- "privileges": [
- "read",
- "modify"
]
}
]
}
Delete tenant role
Authorizations:
path Parameters
tenantId required | string <uuid> Example: 21b54338-6cf2-441b-b6b5-371f1a0a304b Id of the tenant on whose behalf you are acting ((normally) your own tenant). |
tenantRoleId required | string Example: urn:macma-tenant-role:28b0e854-d67c-408e-a9af-ae1bca75db5c:TestTenantRole Id of a tenant role. |
Responses
Response samples
- 400
- 403
- 404
- 500
- 503
{- "error": {
- "message": "Invalid content. Object has missing required properties ([{property1},{property2}])"
}
}
Add role to a user
Authorizations:
path Parameters
tenantId required | string <uuid> Example: 21b54338-6cf2-441b-b6b5-371f1a0a304b Id of the tenant on whose behalf you are acting ((normally) your own tenant). |
tenantRoleId required | string Example: urn:macma-tenant-role:28b0e854-d67c-408e-a9af-ae1bca75db5c:TestTenantRole Id of a tenant role. |
userId required | string <uuid> Example: 1022bc8e-9df7-4703-bd01-a160cffc6bdb Id of the user. |
Responses
Response samples
- 400
- 403
- 404
- 422
- 500
- 503
{- "error": {
- "message": "Invalid content. Object has missing required properties ([{property1},{property2}])"
}
}
Remove user from a role
Authorizations:
path Parameters
tenantId required | string <uuid> Example: 21b54338-6cf2-441b-b6b5-371f1a0a304b Id of the tenant on whose behalf you are acting ((normally) your own tenant). |
tenantRoleId required | string Example: urn:macma-tenant-role:28b0e854-d67c-408e-a9af-ae1bca75db5c:TestTenantRole Id of a tenant role. |
userId required | string <uuid> Example: 1022bc8e-9df7-4703-bd01-a160cffc6bdb Id of the user. |
Responses
Response samples
- 400
- 403
- 404
- 422
- 500
{- "error": {
- "message": "Invalid content. Object has missing required properties ([{property1},{property2}])"
}
}
List users of tenant
List all users of the given tenant.
Authorizations:
path Parameters
tenantId required | string <uuid> Example: 21b54338-6cf2-441b-b6b5-371f1a0a304b Id of the tenant on whose behalf you are acting ((normally) your own tenant). |
query Parameters
start | integer Example: start=0 Starting page index which is starting by 0 (default 0). |
count | integer Example: count=100 Number of items to return per call (pageSize, default 100). |
search | string A String contained in username, first or last name, or email. |
employeeId | string <= 255 characters EmployeeId of the user. The query parameter "search" and "employeeId" are mutually exclusive. You can EITHER provide "search" OR "employeeId" |
Responses
Response samples
- 200
- 400
- 403
- 404
- 500
{- "itemCount": 1,
- "currentPage": 0,
- "pageSize": 10,
- "items": [
- {
- "id": "634cea45-c812-461d-bd8c-6bda08ce7ee9",
- "username": "administrator",
- "firstName": "Max",
- "lastName": "Smith",
- "email": "example@address.com",
- "phoneNumber": "+(11)22 33",
- "employeeId": "mvm5gr"
}
]
}
Create user
Authorizations:
path Parameters
tenantId required | string <uuid> Example: 21b54338-6cf2-441b-b6b5-371f1a0a304b Id of the tenant on whose behalf you are acting ((normally) your own tenant). |
Request Body schema: application/jsonrequired
username required | string [ 1 .. 255 ] characters |
firstName | string [ 1 .. 255 ] characters |
lastName | string [ 1 .. 255 ] characters |
string <email> [ 1 .. 76 ] characters | |
phoneNumber | string [ 0 .. 255 ] characters |
employeeId | string [ 0 .. 255 ] characters |
Responses
Request samples
- Payload
{- "username": "administrator",
- "firstName": "Max",
- "lastName": "Smith",
- "email": "example@address.com",
- "phoneNumber": "+(11)22 33",
- "employeeId": "mvm5gr"
}
Response samples
- 201
- 400
- 403
- 409
- 500
{- "id": "634cea45-c812-461d-bd8c-6bda08ce7ee9",
- "username": "administrator",
- "firstName": "Max",
- "lastName": "Smith",
- "email": "example@address.com",
- "phoneNumber": "+(11)22 33",
- "employeeId": "mvm5gr"
}
Read list of users by user id
Read list of users given as user ids (max 500 items)
Authorizations:
path Parameters
tenantId required | string <uuid> Example: 21b54338-6cf2-441b-b6b5-371f1a0a304b Id of the tenant on whose behalf you are acting ((normally) your own tenant). |
Request Body schema: application/jsonrequired
array of user ids, cannot be empty
items | Array of strings <uuid> <= 500 items [ items <uuid > ] |
Responses
Request samples
- Payload
{- "items": [
- "497f6eca-6276-4993-bfeb-53cbbbba6f08"
]
}
Response samples
- 200
- 400
- 403
- 500
{- "itemCount": 1,
- "currentPage": 0,
- "pageSize": 10,
- "items": [
- {
- "id": "634cea45-c812-461d-bd8c-6bda08ce7ee9",
- "username": "administrator",
- "firstName": "Max",
- "lastName": "Smith",
- "email": "example@address.com",
- "phoneNumber": "+(11)22 33",
- "employeeId": "mvm5gr"
}
]
}
Read user
Read the user by providing its id.
Authorizations:
path Parameters
tenantId required | string <uuid> Example: 21b54338-6cf2-441b-b6b5-371f1a0a304b Id of the tenant on whose behalf you are acting ((normally) your own tenant). |
userId required | string <uuid> Example: 1022bc8e-9df7-4703-bd01-a160cffc6bdb Id of the user. |
Responses
Response samples
- 200
- 403
- 404
- 500
{- "id": "634cea45-c812-461d-bd8c-6bda08ce7ee9",
- "username": "administrator",
- "firstName": "Max",
- "lastName": "Smith",
- "email": "example@address.com",
- "hasLocalIdentity": true,
- "hasFederationLink": false,
- "hasFederatedIdentity": false,
- "phoneNumber": "+(11)22 33",
- "employeeId": "mvm5gr"
}
Delete user
Authorizations:
path Parameters
tenantId required | string <uuid> Example: 21b54338-6cf2-441b-b6b5-371f1a0a304b Id of the tenant on whose behalf you are acting ((normally) your own tenant). |
userId required | string <uuid> Example: 1022bc8e-9df7-4703-bd01-a160cffc6bdb Id of the user. |
Responses
Response samples
- 400
- 403
- 404
- 500
{- "error": {
- "message": "Invalid content. Object has missing required properties ([{property1},{property2}])"
}
}
Reset password
Authorizations:
path Parameters
tenantId required | string <uuid> Example: 21b54338-6cf2-441b-b6b5-371f1a0a304b Id of the tenant on whose behalf you are acting ((normally) your own tenant). |
userId required | string <uuid> Example: 1022bc8e-9df7-4703-bd01-a160cffc6bdb Id of the user. |
Request Body schema: application/jsonrequired
password required | string The new password |
Responses
Request samples
- Payload
{- "password": "my-new-password!"
}
Response samples
- 400
- 403
- 404
- 500
{- "error": {
- "message": "Invalid content. Object has missing required properties ([{property1},{property2}])"
}
}
List groups of user
List all groups of the given user.
Authorizations:
path Parameters
tenantId required | string <uuid> Example: 21b54338-6cf2-441b-b6b5-371f1a0a304b Id of the tenant on whose behalf you are acting ((normally) your own tenant). |
userId required | string <uuid> Example: 1022bc8e-9df7-4703-bd01-a160cffc6bdb Id of the user. |
query Parameters
start | integer Example: start=0 Starting page index which is starting by 0 (default 0). |
count | integer Example: count=100 Number of items to return per call (pageSize, default 100). |
search | string A String contained in the group name, case insensitive. |
Responses
Response samples
- 200
- 403
- 404
- 500
{- "itemCount": 1,
- "currentPage": 0,
- "pageSize": 0,
- "items": [
- {
- "id": "2ba1f8b3-16f9-4b9c-833c-159fb53a9882",
- "parentId": "78de80f1-11f4-4590-92f8-1dd204b5d491",
- "name": "Group name",
- "groups": [
- {
- "id": "d9e06332-e3f7-4d94-9436-d7b98a52f40d",
- "name": "Subgroup 1",
- "parentId": "2080259f-e765-404b-85c1-97ceff170cd0",
- "groups": [ ]
}, - {
- "id": "0bd3b716-481e-40f9-bcbc-6f72242a8175",
- "name": "Subgroup 2",
- "parentId": "2080259f-e765-404b-85c1-97ceff170cd0",
- "groups": [
- {
- "id": "6224ca11-2e70-4913-8094-785ba6fc5ff1",
- "name": "Subgroup 2.1",
- "parentId": "0bd3b716-481e-40f9-bcbc-6f72242a8175",
- "groups": [ ]
}
]
}
], - "applicationIds": [
- [
- "macma",
- "1s74m3t8xfto0142b49yy3wgjb"
]
], - "configurationPrefix": false
}
]
}
List groups of tenant
List all groups of the given tenant.
Authorizations:
path Parameters
tenantId required | string <uuid> Example: 21b54338-6cf2-441b-b6b5-371f1a0a304b Id of the tenant on whose behalf you are acting ((normally) your own tenant). |
query Parameters
start | integer Example: start=0 Starting page index which is starting by 0 (default 0). |
count | integer Example: count=100 Number of items to return per call (pageSize, default 100). |
search | string A String contained in name. |
applicationId | string The identifier of an application. |
taggedGroupsAsFlatList | boolean Flag to return a flat list for all tagged group. Only applicable if applicationId is present. |
Responses
Response samples
- 200
- 403
- 404
- 500
{- "itemCount": 1,
- "currentPage": 0,
- "pageSize": 0,
- "items": [
- {
- "id": "2ba1f8b3-16f9-4b9c-833c-159fb53a9882",
- "parentId": "78de80f1-11f4-4590-92f8-1dd204b5d491",
- "name": "Group name",
- "groups": [
- {
- "id": "d9e06332-e3f7-4d94-9436-d7b98a52f40d",
- "name": "Subgroup 1",
- "parentId": "2080259f-e765-404b-85c1-97ceff170cd0",
- "groups": [ ]
}, - {
- "id": "0bd3b716-481e-40f9-bcbc-6f72242a8175",
- "name": "Subgroup 2",
- "parentId": "2080259f-e765-404b-85c1-97ceff170cd0",
- "groups": [
- {
- "id": "6224ca11-2e70-4913-8094-785ba6fc5ff1",
- "name": "Subgroup 2.1",
- "parentId": "0bd3b716-481e-40f9-bcbc-6f72242a8175",
- "groups": [ ]
}
]
}
], - "applicationIds": [
- [
- "macma",
- "1s74m3t8xfto0142b49yy3wgjb"
]
], - "configurationPrefix": false
}
]
}
Create group
Authorizations:
path Parameters
tenantId required | string <uuid> Example: 21b54338-6cf2-441b-b6b5-371f1a0a304b Id of the tenant on whose behalf you are acting ((normally) your own tenant). |
Request Body schema: application/jsonrequired
name required | string^[a-zA-Z0-9ßüöäÜÖÄ\s\-_+=()\[\]#.@&%!',;$]+(?... |
parentId | string <uuid> The id of the parent group. Groups without parentId are top level groups. |
Responses
Request samples
- Payload
{- "name": "Group name",
- "parentId": "78de80f1-11f4-4590-92f8-1dd204b5d491"
}
Response samples
- 201
- 400
- 403
- 409
- 500
{- "id": "2ba1f8b3-16f9-4b9c-833c-159fb53a9882",
- "parentId": "78de80f1-11f4-4590-92f8-1dd204b5d491",
- "name": "Group name",
- "groups": [
- {
- "id": "d9e06332-e3f7-4d94-9436-d7b98a52f40d",
- "name": "Subgroup 1",
- "parentId": "2080259f-e765-404b-85c1-97ceff170cd0",
- "groups": [ ]
}, - {
- "id": "0bd3b716-481e-40f9-bcbc-6f72242a8175",
- "name": "Subgroup 2",
- "parentId": "2080259f-e765-404b-85c1-97ceff170cd0",
- "groups": [
- {
- "id": "6224ca11-2e70-4913-8094-785ba6fc5ff1",
- "name": "Subgroup 2.1",
- "parentId": "0bd3b716-481e-40f9-bcbc-6f72242a8175",
- "groups": [ ]
}
]
}
], - "applicationIds": [
- [
- "macma",
- "1s74m3t8xfto0142b49yy3wgjb"
]
], - "configurationPrefix": false
}
Read group
Read the group by providing its id.
Authorizations:
path Parameters
tenantId required | string <uuid> Example: 21b54338-6cf2-441b-b6b5-371f1a0a304b Id of the tenant on whose behalf you are acting ((normally) your own tenant). |
groupId required | string <uuid> Example: 7b7a96f2-3098-4a71-bb77-27423da6331b Id of the group. |
Responses
Response samples
- 200
- 400
- 403
- 404
- 500
{- "id": "2ba1f8b3-16f9-4b9c-833c-159fb53a9882",
- "parentId": "78de80f1-11f4-4590-92f8-1dd204b5d491",
- "name": "Group name",
- "groups": [
- {
- "id": "d9e06332-e3f7-4d94-9436-d7b98a52f40d",
- "name": "Subgroup 1",
- "parentId": "2080259f-e765-404b-85c1-97ceff170cd0",
- "groups": [ ]
}, - {
- "id": "0bd3b716-481e-40f9-bcbc-6f72242a8175",
- "name": "Subgroup 2",
- "parentId": "2080259f-e765-404b-85c1-97ceff170cd0",
- "groups": [
- {
- "id": "6224ca11-2e70-4913-8094-785ba6fc5ff1",
- "name": "Subgroup 2.1",
- "parentId": "0bd3b716-481e-40f9-bcbc-6f72242a8175",
- "groups": [ ]
}
]
}
], - "applicationIds": [
- [
- "macma",
- "1s74m3t8xfto0142b49yy3wgjb"
]
], - "configurationPrefix": false
}
Update group
Authorizations:
path Parameters
tenantId required | string <uuid> Example: 21b54338-6cf2-441b-b6b5-371f1a0a304b Id of the tenant on whose behalf you are acting ((normally) your own tenant). |
groupId required | string <uuid> Example: 7b7a96f2-3098-4a71-bb77-27423da6331b Id of the group. |
Request Body schema: application/jsonrequired
name required | string^[a-zA-Z0-9ßüöäÜÖÄ\s\-_+=()\[\]#.@&%!',;$]+(?... |
parentId | string <uuid> The id of the parent group. Groups without parentId are top level groups. |
Responses
Request samples
- Payload
{- "name": "Group name",
- "parentId": "78de80f1-11f4-4590-92f8-1dd204b5d491"
}
Response samples
- 200
- 400
- 403
- 404
- 409
- 500
{- "id": "2ba1f8b3-16f9-4b9c-833c-159fb53a9882",
- "parentId": "78de80f1-11f4-4590-92f8-1dd204b5d491",
- "name": "Group name",
- "groups": [
- {
- "id": "d9e06332-e3f7-4d94-9436-d7b98a52f40d",
- "name": "Subgroup 1",
- "parentId": "2080259f-e765-404b-85c1-97ceff170cd0",
- "groups": [ ]
}, - {
- "id": "0bd3b716-481e-40f9-bcbc-6f72242a8175",
- "name": "Subgroup 2",
- "parentId": "2080259f-e765-404b-85c1-97ceff170cd0",
- "groups": [
- {
- "id": "6224ca11-2e70-4913-8094-785ba6fc5ff1",
- "name": "Subgroup 2.1",
- "parentId": "0bd3b716-481e-40f9-bcbc-6f72242a8175",
- "groups": [ ]
}
]
}
], - "applicationIds": [
- [
- "macma",
- "1s74m3t8xfto0142b49yy3wgjb"
]
], - "configurationPrefix": false
}
Delete group
Authorizations:
path Parameters
tenantId required | string <uuid> Example: 21b54338-6cf2-441b-b6b5-371f1a0a304b Id of the tenant on whose behalf you are acting ((normally) your own tenant). |
groupId required | string <uuid> Example: 7b7a96f2-3098-4a71-bb77-27423da6331b Id of the group. |
Responses
Response samples
- 400
- 403
- 404
- 500
{- "error": {
- "message": "Invalid content. Object has missing required properties ([{property1},{property2}])"
}
}
List users of group
List all users of the given group.
Authorizations:
path Parameters
tenantId required | string <uuid> Example: 21b54338-6cf2-441b-b6b5-371f1a0a304b Id of the tenant on whose behalf you are acting ((normally) your own tenant). |
groupId required | string <uuid> Example: 7b7a96f2-3098-4a71-bb77-27423da6331b Id of the group. |
query Parameters
start | integer Example: start=0 Starting page index which is starting by 0 (default 0). |
count | integer Example: count=100 Number of items to return per call (pageSize, default 100). |
Responses
Response samples
- 200
- 400
- 403
- 404
- 500
{- "itemCount": 1,
- "currentPage": 0,
- "pageSize": 10,
- "items": [
- {
- "id": "634cea45-c812-461d-bd8c-6bda08ce7ee9",
- "username": "administrator",
- "firstName": "Max",
- "lastName": "Smith",
- "email": "example@address.com",
- "phoneNumber": "+(11)22 33",
- "employeeId": "mvm5gr"
}
]
}
Read tenant- and application-roles of a group
Authorizations:
path Parameters
tenantId required | string <uuid> Example: 21b54338-6cf2-441b-b6b5-371f1a0a304b Id of the tenant on whose behalf you are acting ((normally) your own tenant). |
groupId required | string <uuid> Example: 7b7a96f2-3098-4a71-bb77-27423da6331b Id of the group. |
query Parameters
start | integer Example: start=0 Starting page index which is starting by 0 (default 0). |
count | integer Example: count=100 Number of items to return per call (pageSize, default 100). |
type | string Enum: "application" "tenant" Type of roles to return. |
Responses
Response samples
- 200
- 400
- 403
- 404
- 500
- 503
{- "currentPage": 0,
- "pageSize": 10,
- "itemCount": 2,
- "items": [
- {
- "id": "urn:macma-tenant-role:7311ea8c-5d48-43fe-acf9-980eedf24b6c:iot-developer",
- "name": "iot-developer",
- "displayName": "IoT Developer",
- "description": "has advanced access",
- "type": "macma-tenant-role",
- "owningTenantId": "7311ea8c-5d48-43fe-acf9-980eedf24b6c",
- "owningTenantName": "Example Inc"
}
]
}
Add a tenant role to a group
Authorizations:
path Parameters
tenantId required | string <uuid> Example: 21b54338-6cf2-441b-b6b5-371f1a0a304b Id of the tenant on whose behalf you are acting ((normally) your own tenant). |
groupId required | string <uuid> Example: 7b7a96f2-3098-4a71-bb77-27423da6331b Id of the group. |
tenantRoleId required | string Example: urn:macma-tenant-role:28b0e854-d67c-408e-a9af-ae1bca75db5c:TestTenantRole Id of a tenant role. |
Responses
Response samples
- 400
- 403
- 404
- 422
- 500
- 503
{- "error": {
- "message": "Invalid content. Object has missing required properties ([{property1},{property2}])"
}
}
Remove a tenant role from a group
Authorizations:
path Parameters
tenantId required | string <uuid> Example: 21b54338-6cf2-441b-b6b5-371f1a0a304b Id of the tenant on whose behalf you are acting ((normally) your own tenant). |
groupId required | string <uuid> Example: 7b7a96f2-3098-4a71-bb77-27423da6331b Id of the group. |
tenantRoleId required | string Example: urn:macma-tenant-role:28b0e854-d67c-408e-a9af-ae1bca75db5c:TestTenantRole Id of a tenant role. |
Responses
Response samples
- 400
- 403
- 404
- 422
- 500
- 503
{- "error": {
- "message": "Invalid content. Object has missing required properties ([{property1},{property2}])"
}
}
Tag groups with applicationIds
Authorizations:
path Parameters
tenantId required | string <uuid> Example: 21b54338-6cf2-441b-b6b5-371f1a0a304b Id of the tenant on whose behalf you are acting ((normally) your own tenant). |
groupId required | string <uuid> Example: 7b7a96f2-3098-4a71-bb77-27423da6331b Id of the group. |
Request Body schema: application/json
applicationIds required | Array of strings unique List of ids of an application. |
Responses
Request samples
- Payload
{- "applicationIds": [
- "01300ataq111ues1m4lecptx"
]
}
Response samples
- 200
- 400
- 403
- 404
- 500
{- "applicationIds": [
- "01300ataq111ues1m4lecptx"
]
}
Search identity provider mappers
Authorizations:
path Parameters
tenantId required | string <uuid> Example: 21b54338-6cf2-441b-b6b5-371f1a0a304b Id of the tenant on whose behalf you are acting ((normally) your own tenant). |
alias required | string Alias of the identity provider. |
Responses
Response samples
- 200
- 400
- 403
- 404
- 500
{- "itemCount": 1,
- "currentPage": 0,
- "pageSize": 10,
- "items": [
- {
- "id": "634cea45-c812-461d-bd8c-6bda08ce7ee9",
- "name": "oidc-auth-provider-mapper-A",
- "source": "lastName",
- "target": "family_name",
- "type": "Advanced claim to group",
- "syncModeOverride": "INHERIT",
- "groupId": "634cea45-c812-461d-bd8c-6bda08ce7ee9",
- "groupPath": "/example/path/group"
}
]
}
Create identity provider mapper
Authorizations:
path Parameters
tenantId required | string <uuid> Example: 21b54338-6cf2-441b-b6b5-371f1a0a304b Id of the tenant on whose behalf you are acting ((normally) your own tenant). |
alias required | string Alias of the identity provider. |
Request Body schema: application/jsonrequired
name required | string The name of the identity provider mapper. |
source required | string [ 1 .. 255 ] characters source field name. |
target required | string [ 1 .. 255 ] characters target field name. |
type required | string Enum: "oidc-advanced-group-idp-mapper" "oidc-user-attribute-idp-mapper" "oidc-username-idp-mapper" Type of the identity provider mapper |
syncModeOverride required | string Enum: "INHERIT" "IMPORT" "LEGACY" "FORCE" Sync mode override |
groupId | string groupId |
groupPath | string Path of the group |
Responses
Request samples
- Payload
{- "name": "oidc-auth-provider-mapper-A",
- "source": "lastName",
- "target": "family_name",
- "type": "oidc-advanced-group-idp-mapper",
- "syncModeOverride": "INHERIT",
- "groupId": "634cea45-c812-461d-bd8c-6bda08ce7ee9",
- "groupPath": "/example/path/group"
}
Response samples
- 201
- 400
- 403
- 404
- 500
{- "id": "634cea45-c812-461d-bd8c-6bda08ce7ee9",
- "name": "oidc-auth-provider-mapper-A",
- "source": "lastName",
- "target": "family_name",
- "type": "Advanced claim to group",
- "syncModeOverride": "INHERIT",
- "groupId": "634cea45-c812-461d-bd8c-6bda08ce7ee9",
- "groupPath": "/example/path/group"
}
Update identity provider mapper
Authorizations:
path Parameters
tenantId required | string <uuid> Example: 21b54338-6cf2-441b-b6b5-371f1a0a304b Id of the tenant on whose behalf you are acting ((normally) your own tenant). |
alias required | string Alias of the identity provider. |
mapperId required | string id of of the identity provider mapper. |
Request Body schema: application/jsonrequired
name required | string The name of the identity provider mapper. |
source required | string [ 1 .. 255 ] characters source field name. |
target required | string [ 1 .. 255 ] characters target field name. |
type required | string Enum: "oidc-advanced-group-idp-mapper" "oidc-user-attribute-idp-mapper" "oidc-username-idp-mapper" Type of the identity provider mapper |
syncModeOverride required | string Enum: "INHERIT" "IMPORT" "LEGACY" "FORCE" Sync mode override |
groupId | string groupId |
groupPath | string Path of the group |
Responses
Request samples
- Payload
{- "name": "oidc-auth-provider-mapper-A",
- "source": "lastName",
- "target": "family_name",
- "type": "oidc-advanced-group-idp-mapper",
- "syncModeOverride": "INHERIT",
- "groupId": "634cea45-c812-461d-bd8c-6bda08ce7ee9",
- "groupPath": "/example/path/group"
}
Response samples
- 200
- 400
- 403
- 404
- 500
{- "id": "634cea45-c812-461d-bd8c-6bda08ce7ee9",
- "name": "oidc-auth-provider-mapper-A",
- "source": "lastName",
- "target": "family_name",
- "type": "Advanced claim to group",
- "syncModeOverride": "INHERIT",
- "groupId": "634cea45-c812-461d-bd8c-6bda08ce7ee9",
- "groupPath": "/example/path/group"
}
Delete identity provider mapper
Authorizations:
path Parameters
tenantId required | string <uuid> Example: 21b54338-6cf2-441b-b6b5-371f1a0a304b Id of the tenant on whose behalf you are acting ((normally) your own tenant). |
alias required | string Alias of the identity provider. |
mapperId required | string Identity provider mapper Id |
Responses
Response samples
- 400
- 403
- 404
- 422
- 500
{- "error": {
- "message": "Invalid content. Object has missing required properties ([{property1},{property2}])"
}
}
Delete identity provider mapper
Authorizations:
path Parameters
tenantId required | string <uuid> Example: 21b54338-6cf2-441b-b6b5-371f1a0a304b Id of the tenant on whose behalf you are acting ((normally) your own tenant). |
alias required | string Alias of the identity provider. |
mapperId required | string Identity provider mapper Id |
Responses
Response samples
- 400
- 403
- 404
- 422
- 500
{- "error": {
- "message": "Invalid content. Object has missing required properties ([{property1},{property2}])"
}
}