Skip to main content

Overview

The BlueXP federation service manages identity federation between BlueXP and customer identity providers. Identity federation enables single sign-on with BlueXP so that your corporate users can log in using their credentials.

The federation service endpoints also allow your users to configure their notification settings so that they're notified before their identity provider credentials or certificates expire.

The following components are defined within the BlueXP federation service:

  • domain

  • federation

  • unmigrated connection

To configure a federation, all domains that don't match your user's email address must be verified. To verify a domain, you first need to add the domain to BlueXP in order to receive a unique code. You use the code to create a DNS TXT record for the domain, and then you verify the domain in BlueXP.

The federation service replaces the functionality provided through Cloud Central Federation Setup. Federations configured through Cloud Central are "unmigrated connections". The unmigrated connection endpoints enable you to non-disruptively import a connection into a BlueXP organization and manage it through the federation service. After you import a connection, it cannot be managed through Cloud Central Federation Setup.

Note Before using the API reference documentation, review the Get started section for the BlueXP APIs. For more information about the security tokens and identifiers you'll need when using the API, review the Common workflows and tasks section.

REST implementation

HTTP methods

Method Description

POST

Create an object instance

GET

Retrieve an object instance or collection

PATCH

Update an existing object

DELETE

Remove an existing object

Request headers

Request Header Description

Authorization

This header contains a bearer token used to access the BlueXP server.

Content-Type

This representation header is used to indicate the original media type of the resource.

Accept

The server automatically returns content in JSON format if Accept header is not specified.

Query parameters

You can use query parameters with endpoints in the following components:

Component Query Parameter

Domain

include, count, filter, limit, skip, orderBy

Federation

include, count, filter, limit, skip, orderBy

Response headers

This API uses the standard HTTP response headers common with all BlueXP APIs. See REST implementation for more information.

HTTP status codes

HTTP Status Code Description

200

OK: Returned for successful operation completion

202

Accepted: The request was accepted and is currently in process.

204

The operation was completed successfully and the server did not send a response message.

400

Bad Request: Returned if the input is malformed and could not be parsed

401

Unauthorized: Returned if user authentication failed or the token has expired

403

Forbidden: Returned for authorization errors depending on the resource and token.

409

Conflict: The operation failed because another operation is already in progress.

5xx

An unexpected error occurred within the BlueXP server which has prevented it from fulfilling the request.

Error handling

There are three processes involved with error handling and processing:

  • The error is logged for supportability

  • The error is also returned to the caller for any specific handling

  • The database connection is rolled back