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": true,
"force_authn": true,
"session_max_age_hours": 0,
"auto_users_creation": true,
"enable_group_mappings": true
}
]
}

Add new SAML federation

Creates a new SAML federation.

Authorizations:

iam_token_account_scoped

Request Body schema: application/json
required

name	string
description	string
issuer	string
sso_url	string
sign_authn_requests	boolean
force_authn	boolean
session_max_age_hours	integer
auto_users_creation	boolean
enable_group_mappings	boolean

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": true,
"force_authn": true,
"session_max_age_hours": 0,
"auto_users_creation": true,
"enable_group_mappings": true
}

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": true,
"force_authn": true,
"session_max_age_hours": 0,
"auto_users_creation": true,
"enable_group_mappings": true
}

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 information

Returns the federation's 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": true,
"force_authn": true,
"session_max_age_hours": 0,
"auto_users_creation": true,
"enable_group_mappings": true
}

Update SAML federation's info

Partially updates the federation's 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
description	string
alias	string
issuer	string
sso_url	string
sign_authn_requests	boolean
force_authn	boolean
session_max_age_hours	integer
auto_users_creation	boolean
enable_group_mappings	boolean

Responses

Request samples

Payload

Content type

application/json

{"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": true,
"force_authn": true,
"session_max_age_hours": 0,
"auto_users_creation": true,
"enable_group_mappings": true
}

Response samples

401
403
404
500

Content type

application/json

{"code": "string",
"message": "string"
}

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": "string",
"message": "string"
}

Retrieve SAML federation preview data

Returns the federation's 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

Get SAML federation certificates

Returns certificates which are 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",
"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-----"
}
]
}

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
description	string
data required	string

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",
"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-----"
}

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",
"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-----"
}

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
description	string

Responses

Request samples

Payload

Content type

application/json

{"name": "certificate name",
"description": "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": "certificate name",
"description": "certificate description",
"not_before": "2023-06-23T11:26:48Z",
"not_after": "2033-06-23T11:28:28Z",
"fingerprint": "6A822A2645D9A18D1CC40D5B5BDA444AA579AF3B399AF77309ABD5222CC23FC0",
"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-----"
}

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": "string",
"message": "string"
}

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": "string",
"external_group_id": "string"
}
]
}

Update SAML group mapping

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}$
external_group_id	string [ 1 .. 255 ] characters

Responses

Request samples

Payload

Content type

application/json

{"group_mappings": [{"internal_group_id": "string",
"external_group_id": "string"
}
]
}

Response samples

Content type

application/json

{"group_mappings": [{"internal_group_id": "string",
"external_group_id": "string"
}
]
}

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": "string",
"message": "string"
}

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": "string",
"message": "string"
}

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": "string",
"message": "string"
}

Federations API (v1.0.0)

SAML federations

List SAML federations

Authorizations:

Responses

Response samples

Add new SAML federation

Authorizations:

Request Body schema: application/jsonrequired

Responses

Request samples

Response samples

Get SAML federation status

path Parameters

Responses

Get SAML federation information

Authorizations:

path Parameters

Responses

Response samples

Update SAML federation's info

Authorizations:

path Parameters

Request Body schema: application/jsonrequired

Responses

Request samples

Response samples

Delete SAML federation

Authorizations:

path Parameters

Responses

Response samples

Retrieve SAML federation preview data

path Parameters

Responses

Response samples

SAML certificates

Get 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 mapping

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