Federations API (v1.0.0)

Managing federations and certificates

SAML federations

List SAML federations

Returns a list of all configured SAML federations.

Authorizations:

iam_token_account_scoped

Responses

Response samples

200
401
403
500

Content type

application/json

{"federations": [{"account_id": "242137",
"id": "e35a6d85-9a81-4d03-9c93-424714708fe0",
"name": "federation name",
"description": "simple description",
"alias": "custom-federation",
"issuer": "https://idp.example.com/realms/master",
"sso_url": "https://idp.example.com/realms/master/protocol/saml",
"sign_authn_requests": false,
"force_authn": false,
"session_max_age_hours": 8,
"auto_users_creation": true,
"enable_group_mappings": false
}
]
}

Create SAML federation

Creates a new SAML federation.

Authorizations:

iam_token_account_scoped

Request Body schema: application/json
required

name	string Federation name.
description	string Federation description.
issuer	string Identity provider issuer URL.
sso_url	string Single Sign-On URL of the identity provider.
sign_authn_requests	boolean Indicates whether authentication requests should be signed.
force_authn	boolean Indicates whether the identity provider must reauthenticate the user.
session_max_age_hours	integer Maximum session duration in hours.
auto_users_creation	boolean Indicates whether users are automatically created upon first login.
enable_group_mappings	boolean Indicates whether group mappings are enabled for the federation.

Responses

Request samples

Payload

Content type

application/json

{"name": "federation name",
"description": "simple description",
"issuer": "https://idp.example.com/realms/master",
"sso_url": "https://idp.example.com/realms/master/protocol/saml",
"sign_authn_requests": false,
"force_authn": false,
"session_max_age_hours": 8,
"auto_users_creation": true,
"enable_group_mappings": false
}

Response samples

200
400
401
403
500

Content type

application/json

{"account_id": "242137",
"id": "e35a6d85-9a81-4d03-9c93-424714708fe0",
"name": "federation name",
"description": "simple description",
"alias": "custom-federation",
"issuer": "https://idp.example.com/realms/master",
"sso_url": "https://idp.example.com/realms/master/protocol/saml",
"sign_authn_requests": false,
"force_authn": false,
"session_max_age_hours": 8,
"auto_users_creation": true,
"enable_group_mappings": false
}

Get SAML federation status

Returns the status of the specified federation without the response body. Does not require authentication.

path Parameters

federation_id

required

string <uuid>

Federation identifier in the UUID v4 format.

Responses

Get SAML federation data

Returns the federation name, issuer, SSO URL, and other settings.

Authorizations:

iam_token_account_scoped

path Parameters

federation_id

required

string <uuid>

Federation identifier in the UUID v4 format.

Responses

Response samples

200
401
403
404
500

Content type

application/json

{"account_id": "242137",
"id": "e35a6d85-9a81-4d03-9c93-424714708fe0",
"name": "federation name",
"description": "simple description",
"alias": "custom-federation",
"issuer": "https://idp.example.com/realms/master",
"sso_url": "https://idp.example.com/realms/master/protocol/saml",
"sign_authn_requests": false,
"force_authn": false,
"session_max_age_hours": 8,
"auto_users_creation": true,
"enable_group_mappings": false
}

Update SAML federation data

Partially updates the federation name, description, alias, issuer, SSO URL, or other settings.

Authorizations:

iam_token_account_scoped

path Parameters

federation_id

required

string <uuid>

Federation identifier in the UUID v4 format.

Request Body schema: application/json
required

name	string Federation name.
description	string Federation description.
alias	string Federation alias used in login URLs.
issuer	string Identity provider issuer URL.
sso_url	string Single Sign-On URL of the identity provider.
sign_authn_requests	boolean Indicates whether authentication requests should be signed.
force_authn	boolean Indicates whether the identity provider must reauthenticate the user.
session_max_age_hours	integer Maximum session duration in hours.
auto_users_creation	boolean Indicates whether users are automatically created upon first login.
enable_group_mappings	boolean Indicates whether group mappings are enabled for the federation.

Responses

Request samples

Payload

Content type

application/json

{"name": "updated federation name",
"description": "updated description",
"alias": "custom-federation",
"issuer": "https://idp.example.com/realms/master",
"sso_url": "https://idp.example.com/realms/master/protocol/saml",
"sign_authn_requests": true,
"force_authn": true,
"session_max_age_hours": 12,
"auto_users_creation": false,
"enable_group_mappings": true
}

Response samples

401
403
404
500

Content type

application/json

{"code": "UNAUTHORIZED",
"message": "Unauthorized"
}

Delete SAML federation

Deletes the specified federation and all its associated data.

Authorizations:

iam_token_account_scoped

path Parameters

federation_id

required

string <uuid>

Federation identifier in the UUID v4 format.

Responses

Response samples

401
403
404
500

Content type

application/json

{"code": "UNAUTHORIZED",
"message": "Unauthorized"
}

Get SAML/OIDC federation preview data

Returns the federation name, description, and alias. Does not require authentication.

path Parameters

federation_id

required

string

Federation identifier in the UUID v4 format or configured alias name.

Responses

Response samples

200
404
500

Content type

application/json

{"id": "e35a6d85-9a81-4d03-9c93-424714708fe0",
"name": "federation name",
"description": "simple description",
"alias": "custom.federation"
}

SAML certificates

List SAML federation certificates

Returns a list of certificates used in the specified SAML federation.

Authorizations:

iam_token_account_scoped

path Parameters

federation_id

required

string <uuid>

Federation identifier in the UUID v4 format.

Responses

Response samples

200
401
403
404
500

Content type

application/json

{"certificates": [{"id": "bcceb50a-e4a3-404f-8391-f319e40c1fd5",
"account_id": "242137",
"federation_id": "f9a51b33-9194-4d44-a959-43740b6334a4",
"name": "certificate name",
"description": "certificate description",
"not_before": "2023-06-23T11:26:48Z",
"not_after": "2033-06-23T11:28:28Z",
"fingerprint": "6A822A2645D9A18D1CC40D5B5BDA444AA579AF3B399AF77309ABD5222CC23FC0"
}
]
}

Upload certificate

Uploads a new certificate for the specified federation.

Authorizations:

iam_token_account_scoped

path Parameters

federation_id

required

string <uuid>

Federation identifier in the UUID v4 format.

Request Body schema: application/json
required

name required	string Certificate name.
description	string Certificate description.
data required	string PEM-encoded certificate data.

Responses

Request samples

Payload

Content type

application/json

{"name": "certificate name",
"description": "certificate description",
"data": "-----BEGIN CERTIFICATE-----\nMIICmzCCAYMCBgGI6ANFczANBgkqhkiG9w0BAQsFADARMQ8wDQYDVQQDDAZtYXN0ZXIwHhcNMjMwNjIzMTEyNjQ4WhcNMzMwNjIzMTEyODI4WjARMQ8wDQYDVQQDDAZtYXN0ZXIwggEiMA0GCSqGSIb3DQEBAQUAA4IBDwAwggEKAoIBAQC04rOaDpre/MucE3HXVCnAnpqIqQOeMn696AW2FATnI26x1BsxVAGjcrheAOIu+CxC28m48Ah4+SiTEk/u2X/WbGTd/1GZooz37cge0AWMQGyh8ysZRd6q06kg4QGD1iUtdQyHioMbSr9pPne2QQgSX5/gM9XDuA6dpG9Yv0PIPLFlk3BIUL1qEfUiYbDlrunkN/y4XromJaJPpgXKWraH194bqcgXGQLrCqicKwsRBoQJHg3ODWHjHFOwYODJ1XBsRcAue4J88PKiPV1tZNPVczMptrkqGBYTgOYGjKXGe5EH50RJE4/3Ynurz2s34DSDVJhJOYtGwpfeSuU3i3mVAgMBAAEwDQYJKoZIhvcNAQELBQADggEBAGAweCuWJmJXMUdRtgoFIiu6BGotDX5sA/VOm4CRsEXV7/qnBagrAPkRz86KGm4lOPL0X+I13JQh4/OB1gxnPN+BXhNtCWCoj1wA3/BWjs1ow/gaVXzwdy+1mbc/sUBudsLq2Yqs54GgeYsTBKMVpSLKiRg1NebEFlqFmG2hjPzYg1QHL4VBusMQgqt7TTnOfGtdT3Ss9TKGRQ+iwfNL0BtSAKaTRdhNVU4lDYUs788Kw5od/uJj0wTICKO5/PrkX7Uy42+fyU+4SvJynPOy+M+z+s08JC9+eYXixfeeFG1nNWR+DIKXcXaSwNQW+8RweGbOJxQ2BoUKtl0NCHrvxJw=\n-----END CERTIFICATE-----"
}

Response samples

200
401
403
404
500

Content type

application/json

{"id": "bcceb50a-e4a3-404f-8391-f319e40c1fd5",
"account_id": "242137",
"federation_id": "f9a51b33-9194-4d44-a959-43740b6334a4",
"name": "certificate name",
"description": "certificate description",
"not_before": "2023-06-23T11:26:48Z",
"not_after": "2033-06-23T11:28:28Z",
"fingerprint": "6A822A2645D9A18D1CC40D5B5BDA444AA579AF3B399AF77309ABD5222CC23FC0"
}

Get certificate data

Returns information about the specified certificate.

Authorizations:

iam_token_account_scoped

path Parameters

federation_id required	string <uuid> Federation identifier in the UUID v4 format.
certificate_id required	string Certificate identifier.

Responses

Response samples

200
401
403
404
500

Content type

application/json

{"id": "bcceb50a-e4a3-404f-8391-f319e40c1fd5",
"account_id": "242137",
"federation_id": "f9a51b33-9194-4d44-a959-43740b6334a4",
"name": "certificate name",
"description": "certificate description",
"not_before": "2023-06-23T11:26:48Z",
"not_after": "2033-06-23T11:28:28Z",
"fingerprint": "6A822A2645D9A18D1CC40D5B5BDA444AA579AF3B399AF77309ABD5222CC23FC0"
}

Update SAML certificate data

Partially updates the certificate name or description.

Authorizations:

iam_token_account_scoped

path Parameters

federation_id required	string <uuid> Federation identifier in the UUID v4 format.
certificate_id required	string Certificate identifier.

Request Body schema: application/json
required

name	string Certificate name.
description	string Certificate description.

Responses

Request samples

Payload

Content type

application/json

{"name": "updated certificate name",
"description": "updated certificate description"
}

Response samples

200
401
403
404
500

Content type

application/json

{"id": "bcceb50a-e4a3-404f-8391-f319e40c1fd5",
"account_id": "242137",
"federation_id": "f9a51b33-9194-4d44-a959-43740b6334a4",
"name": "updated certificate name",
"description": "updated certificate description",
"not_before": "2023-06-23T11:26:48Z",
"not_after": "2033-06-23T11:28:28Z",
"fingerprint": "6A822A2645D9A18D1CC40D5B5BDA444AA579AF3B399AF77309ABD5222CC23FC0"
}

Delete certificate

Deletes the specified certificate from the federation.

Authorizations:

iam_token_account_scoped

path Parameters

federation_id required	string <uuid> Federation identifier in the UUID v4 format.
certificate_id required	string Certificate identifier.

Responses

Response samples

401
403
404
500

Content type

application/json

{"code": "UNAUTHORIZED",
"message": "Unauthorized"
}

SAML group mappings

List SAML group mappings

Returns a list of group mappings for the specified federation.

Authorizations:

iam_token_account_scoped

path Parameters

federation_id

required

string

Federation identifier.

Responses

Response samples

200
401
403
404
500

Content type

application/json

{"group_mappings": [{"internal_group_id": "group-1",
"external_group_id": "idp-admins"
}
]
}

Update SAML group mappings

Replaces all group mappings for the specified federation with the provided list.

Authorizations:

iam_token_account_scoped

path Parameters

federation_id

required

string

Federation identifier.

Request Body schema: application/json
required

Array of objects (models.GroupMapping) <= 100 items

Array (<= 100 items)

internal_group_id	string^[A-z0-9-]{1,64}$ IAM group identifier.
external_group_id	string [ 1 .. 255 ] characters External group identifier from the identity provider.

Responses

Request samples

Payload

Content type

application/json

{"group_mappings": [{"internal_group_id": "group-1",
"external_group_id": "idp-admins"
},
{"internal_group_id": "group-2",
"external_group_id": "idp-developers"
}
]
}

Response samples

Content type

application/json

{"group_mappings": [{"internal_group_id": "group-1",
"external_group_id": "idp-admins"
},
{"internal_group_id": "group-2",
"external_group_id": "idp-developers"
}
]
}

Create SAML group mapping

Creates a mapping between an IAM group and an external group.

Authorizations:

iam_token_account_scoped

path Parameters

federation_id required	string Federation identifier.
group_id required	string IAM group identifier.
external_group_id required	string External group identifier.

Responses

Response samples

400
401
403
404
500

Content type

application/json

{"code": "FEDERATION_MAX_NUMBER_EXCEEDED",
"message": "Max number of federations exceeded."
}

Get SAML group mapping status

Checks whether the external group is mapped to the IAM group.

Authorizations:

iam_token_account_scoped

path Parameters

federation_id required	string Federation identifier.
group_id required	string IAM group identifier.
external_group_id required	string External group identifier.

Responses

Response samples

401
403
404
500

Content type

application/json

{"code": "UNAUTHORIZED",
"message": "Unauthorized"
}

Delete SAML group mapping

Deletes the mapping between an IAM group and an external group.

Authorizations:

iam_token_account_scoped

path Parameters

federation_id required	string Federation identifier.
group_id required	string IAM group identifier.
external_group_id required	string External group identifier.

Responses

Response samples

400
401
403
404
500

Content type

application/json

{"code": "FEDERATION_MAX_NUMBER_EXCEEDED",
"message": "Max number of federations exceeded."
}

OIDC federations

List OIDC federations

Returns a list of all configured OIDC federations.

Authorizations:

iam_token_account_scoped

Responses

Response samples

200
401
403
500

Content type

application/json

{"federations": [{"id": "2ee97f11-fa79-46ad-9912-5c876339e2ba",
"account_id": "242137",
"name": "oidc federation name",
"description": "simple description",
"alias": "custom-oidc-federation",
"issuer": "https://idp.example.com/realms/master",
"client_id": "my-client-id",
"auth_url": "https://idp.example.com/realms/master/protocol/openid-connect/auth",
"token_url": "https://idp.example.com/realms/master/protocol/openid-connect/token",
"jwks_url": "https://idp.example.com/realms/master/protocol/openid-connect/certs",
"session_max_age_hours": 8,
"auto_users_creation": true,
"enable_group_mappings": false
}
]
}

Create OIDC federation

Creates a new OIDC federation.

Authorizations:

iam_token_account_scoped

Request Body schema: application/json
required

name required	string [ 1 .. 255 ] characters Federation name.
description	string <= 255 characters Federation description.
alias	string^[A-Za-z0-9_-]{1,255}$ Federation alias used in login URLs.
issuer required	string <= 4096 characters Identity provider issuer URL.
client_id required	string [ 1 .. 255 ] characters Client identifier registered in the identity provider.
client_secret required	string [ 1 .. 255 ] characters Client secret registered in the identity provider.
auth_url required	string Authorization endpoint URL of the identity provider.
token_url required	string Token endpoint URL of the identity provider.
jwks_url required	string JSON Web Key Set endpoint URL of the identity provider.
session_max_age_hours required	integer [ 1 .. 720 ] Maximum session duration in hours.
auto_users_creation	boolean Indicates whether users are automatically created upon first login.
enable_group_mappings	boolean Indicates whether group mappings are enabled for the federation.

Responses

Request samples

Payload

Content type

application/json

{"name": "oidc federation name",
"description": "simple description",
"alias": "custom-oidc-federation",
"issuer": "https://idp.example.com/realms/master",
"client_id": "my-client-id",
"client_secret": "my-client-secret",
"auth_url": "https://idp.example.com/realms/master/protocol/openid-connect/auth",
"token_url": "https://idp.example.com/realms/master/protocol/openid-connect/token",
"jwks_url": "https://idp.example.com/realms/master/protocol/openid-connect/certs",
"session_max_age_hours": 8,
"auto_users_creation": true,
"enable_group_mappings": false
}

Response samples

200
400
401
403
500

Content type

application/json

{"id": "2ee97f11-fa79-46ad-9912-5c876339e2ba",
"account_id": "242137",
"name": "oidc federation name",
"description": "simple description",
"alias": "custom-oidc-federation",
"issuer": "https://idp.example.com/realms/master",
"client_id": "my-client-id",
"auth_url": "https://idp.example.com/realms/master/protocol/openid-connect/auth",
"token_url": "https://idp.example.com/realms/master/protocol/openid-connect/token",
"jwks_url": "https://idp.example.com/realms/master/protocol/openid-connect/certs",
"session_max_age_hours": 8,
"auto_users_creation": true,
"enable_group_mappings": false
}

Get OIDC federation status

Returns the status of the specified federation without the response body.

Authorizations:

iam_token_account_scoped

path Parameters

federation_id

required

string <uuid>

Federation identifier in the UUID v4 format.

Responses

Get OIDC federation data

Returns the federation name, issuer, client ID, endpoint URLs, and other settings.

Authorizations:

iam_token_account_scoped

path Parameters

federation_id

required

string <uuid>

Federation identifier in the UUID v4 format.

Responses

Response samples

200
401
403
404
500

Content type

application/json

{"id": "2ee97f11-fa79-46ad-9912-5c876339e2ba",
"account_id": "242137",
"name": "oidc federation name",
"description": "simple description",
"alias": "custom-oidc-federation",
"issuer": "https://idp.example.com/realms/master",
"client_id": "my-client-id",
"auth_url": "https://idp.example.com/realms/master/protocol/openid-connect/auth",
"token_url": "https://idp.example.com/realms/master/protocol/openid-connect/token",
"jwks_url": "https://idp.example.com/realms/master/protocol/openid-connect/certs",
"session_max_age_hours": 8,
"auto_users_creation": true,
"enable_group_mappings": false
}

Update OIDC federation data

Partially updates the federation name, description, alias, issuer, client credentials, endpoint URLs, or other settings.

Authorizations:

iam_token_account_scoped

path Parameters

federation_id

required

string <uuid>

Federation identifier in the UUID v4 format.

Request Body schema: application/json
required

name	string [ 1 .. 255 ] characters Federation name.
description	string or null <= 255 characters Federation description.
alias	string or null^[A-Za-z0-9_-]{1,255}$ Federation alias used in login URLs.
issuer	string <= 4096 characters Identity provider issuer URL.
client_id	string [ 1 .. 255 ] characters Client identifier registered in the identity provider.
client_secret	string or null [ 1 .. 255 ] characters Client secret registered in the identity provider.
auth_url	string Authorization endpoint URL of the identity provider.
token_url	string Token endpoint URL of the identity provider.
jwks_url	string JSON Web Key Set endpoint URL of the identity provider.
session_max_age_hours	integer or null [ 1 .. 720 ] Maximum session duration in hours.
auto_users_creation	boolean or null Indicates whether users are automatically created upon first login.
enable_group_mappings	boolean or null Indicates whether group mappings are enabled for the federation.

Responses

Request samples

Payload

Content type

application/json

{"name": "updated oidc federation name",
"description": "updated description",
"alias": "custom-oidc-federation",
"issuer": "https://idp.example.com/realms/master",
"client_id": "my-client-id",
"client_secret": "my-new-client-secret",
"auth_url": "https://idp.example.com/realms/master/protocol/openid-connect/auth",
"token_url": "https://idp.example.com/realms/master/protocol/openid-connect/token",
"jwks_url": "https://idp.example.com/realms/master/protocol/openid-connect/certs",
"session_max_age_hours": 12,
"auto_users_creation": false,
"enable_group_mappings": true
}

Response samples

400
401
403
404
500

Content type

application/json

{"code": "FEDERATION_MAX_NUMBER_EXCEEDED",
"message": "Max number of federations exceeded."
}

Delete OIDC federation

Deletes the specified federation and all its associated data.

Authorizations:

iam_token_account_scoped

path Parameters

federation_id

required

string <uuid>

Federation identifier in the UUID v4 format.

Responses

Response samples

401
403
404
500

Content type

application/json

{"code": "UNAUTHORIZED",
"message": "Unauthorized"
}

Get SAML/OIDC federation preview data

Returns the federation name, description, and alias. Does not require authentication.

path Parameters

federation_id

required

string

Federation identifier in the UUID v4 format or configured alias name.

Responses

Response samples

200
404
500

Content type

application/json

{"id": "e35a6d85-9a81-4d03-9c93-424714708fe0",
"name": "federation name",
"description": "simple description",
"alias": "custom.federation"
}

OIDC group mappings

List OIDC group mappings

Returns a list of group mappings for the specified OIDC federation.

Authorizations:

iam_token_account_scoped

path Parameters

federation_id

required

string

Federation identifier.

Responses

Response samples

200
401
403
404
500

Content type

application/json

{"group_mappings": [{"internal_group_id": "group-1",
"external_group_id": "idp-admins"
}
]
}

Update OIDC group mappings

Replaces all group mappings for the specified OIDC federation with the provided list.

Authorizations:

iam_token_account_scoped

path Parameters

federation_id

required

string

Federation identifier.

Request Body schema: application/json
required

Array of objects (models.GroupMapping) <= 100 items

Array (<= 100 items)

internal_group_id	string^[A-z0-9-]{1,64}$ IAM group identifier.
external_group_id	string [ 1 .. 255 ] characters External group identifier from the identity provider.

Responses

Request samples

Payload

Content type

application/json

{"group_mappings": [{"internal_group_id": "group-1",
"external_group_id": "idp-admins"
},
{"internal_group_id": "group-2",
"external_group_id": "idp-developers"
}
]
}

Response samples

400
401
403
404
500

Content type

application/json

{"code": "FEDERATION_MAX_NUMBER_EXCEEDED",
"message": "Max number of federations exceeded."
}

Create OIDC group mapping

Creates a mapping between an IAM group and an external group.

Authorizations:

iam_token_account_scoped

path Parameters

federation_id required	string Federation identifier.
group_id required	string IAM group identifier.
external_group_id required	string External group identifier.

Responses

Response samples

400
401
403
404
500

Content type

application/json

{"code": "FEDERATION_MAX_NUMBER_EXCEEDED",
"message": "Max number of federations exceeded."
}

Get OIDC group mapping status

Checks whether the external group is mapped to the IAM group.

Authorizations:

iam_token_account_scoped

path Parameters

federation_id required	string Federation identifier.
group_id required	string IAM group identifier.
external_group_id required	string External group identifier.

Responses

Response samples

401
403
404
500

Content type

application/json

{"code": "UNAUTHORIZED",
"message": "Unauthorized"
}

Delete OIDC group mapping

Deletes the mapping between an IAM group and an external group.

Authorizations:

iam_token_account_scoped

path Parameters

federation_id required	string Federation identifier.
group_id required	string IAM group identifier.
external_group_id required	string External group identifier.

Responses

Response samples

400
401
403
404
500

Content type

application/json

{"code": "FEDERATION_MAX_NUMBER_EXCEEDED",
"message": "Max number of federations exceeded."
}

Federations API (v1.0.0)

SAML federations

List SAML federations

Authorizations:

Responses

Response samples

Create SAML federation

Authorizations:

Request Body schema: application/jsonrequired

Responses

Request samples

Response samples

Get SAML federation status

path Parameters

Responses

Get SAML federation data

Authorizations:

path Parameters

Responses

Response samples

Update SAML federation data

Authorizations:

path Parameters

Request Body schema: application/jsonrequired

Responses

Request samples

Response samples

Delete SAML federation

Authorizations:

path Parameters

Responses

Response samples

Get SAML/OIDC federation preview data

path Parameters

Responses

Response samples

SAML certificates

List SAML federation certificates

Authorizations:

path Parameters

Responses

Response samples

Upload certificate

Authorizations:

path Parameters

Request Body schema: application/jsonrequired

Responses

Request samples

Response samples

Get certificate data

Authorizations:

path Parameters

Responses

Response samples

Update SAML certificate data

Authorizations:

path Parameters

Request Body schema: application/jsonrequired

Responses

Request samples

Response samples

Delete certificate

Authorizations:

path Parameters

Responses

Response samples

SAML group mappings

List SAML group mappings

Authorizations:

path Parameters

Responses

Response samples

Update SAML group mappings

Authorizations:

path Parameters

Request Body schema: application/jsonrequired

Responses

Request samples

Response samples

Create SAML group mapping

Request Body schema: application/json
required

Request Body schema: application/json
required

Request Body schema: application/json
required

Request Body schema: application/json
required

Request Body schema: application/json
required

Request Body schema: application/json
required

Request Body schema: application/json
required

Request Body schema: application/json
required