Manage My Access

You can use the following Britive API methods to manage the access-related operations of users.

1. Profiles of a User 

The GET method returns all the profiles associated with the user who has an API token.

Request Example

An example GET request for retrieving user profiles is shown here:

curl --location --request GET '{{url}}/api/access' \
--header 'Authorization: TOKEN {{token}}'

Response Example 

An example response of the GET request for retrieving user profiles is shown here:

[
    {
        "appContainerId": "dY4nLiFRMMPzmQz72FsK",
        "appName": "App1",
        "appDescription": "",
        "catalogAppName": "AWS",
        "programmaticAccess": true,
        "profiles": [
            {
                "profileId": "13m3ud7zer5o7uge5yle",
                "profileName": "S3 Full Access",
                "profileDescription": "",
                "environments": [
                    {
                        "environmentId": "1111",
                        "environmentName": "2222 (Labs)",
                        "environmentDescription": "",
                        "alternateEnvironmentName": "Labs",
                        "accountId": "1111"
                    },
                    {
                        "environmentId": "2222",
                        "environmentName": "2222 (Dev)",
                        "environmentDescription": "",
                        "alternateEnvironmentName": "Dev",
                        "accountId": "2222"
                    }
                ]
            }
        ]
    }
]

(Deprecated) Check-out a Profile

The POST method checks out the user profile for the given papID and envID. The papID and envID can be obtained from the Get Profiles API explained in the preceding section. The transactionID returned by this API is used to get the console access URL, the tokens for the supported applications, and to check-in the profile.

Request Example

An example POST request for checking out user profiles is shown here:

curl --location --request POST '{{url}}/api/access/{{papID}}/environments/{{envID}}' \
--header 'Authorization: TOKEN {{token}}'

Response Example 

An example response of the POST request for checking out user profiles is shown here:

{
    "accessStatusId": 13164,
    "userId": 67,
    "transactionId": "user1-3424rmyuw7ml1rnco24wcym",
    "expiration": "2020-10-14T09:44:12Z",
    "checkedOut": "2020-10-14T08:44:12Z",
    "checkedIn": null,
    "currentExtensionIndex": 0,
    "environmentId": "1111",
    "status": "checkedOut",
    "statusText": "Checked Out",
    "papId": "13m3ud7zer5o7uge5yle"
}

2. Check-out a Profile

The POST method checks out the user profile for the given papID and envID. The papID and envID can be obtained from the Get Profiles API explained in the preceding section. The transactionID returned by this API is used to get the console access URL, the tokens for the supported applications, and to check-in the profile. There are two ways to check-out a profile, either by console access or by programmatic access.

2.1 Checkout Console Access for a Profile

Request Example

An example POST request for checking out user profiles is shown here:

curl command - curl --location --request POST '{{url}}/api/access/{{papID}}/environments/{{envID}}?accessType=CONSOLE' \
--header 'Authorization: TOKEN {{token}}'

Response Example 

An example response of the POST request for checking out user profiles is shown here:

{
    "accessStatusId": 13164,
    "userId": 67,
    "transactionId": "user1-3424rmyuw7ml1rnco24wcym",
    "expiration": "2020-10-14T09:44:12Z",
    "checkedOut": "2020-10-14T08:44:12Z",
    "checkedIn": null,
    "currentExtensionIndex": 0,
    "environmentId": "1111",
    "status": "checkedOut",
    "statusText": "Checked Out",
    "papId": "13m3ud7zer5o7uge5yle",
    "accessType" : "CONSOLE"
}

2.2 Checkout Programmatic Access for a Profile

Request Example

An example POST request for checking out user profiles is shown here:

curl command - curl --location --request POST '{{url}}/api/access/{{papID}}/environments/{{envID}}?accessType=PROGRAMMATIC' \
--header 'Authorization: TOKEN {{token}}'

Response Example 

An example response of the POST request for checking out user profiles is shown here:

{
    "accessStatusId": 13164,
    "userId": 67,
    "transactionId": "user1-3424rmyuw7ml1rnco24wcym",
    "expiration": "2020-10-14T09:44:12Z",
    "checkedOut": "2020-10-14T08:44:12Z",
    "checkedIn": null,
    "currentExtensionIndex": 0,
    "environmentId": "1111",
    "status": "checkedOut",
    "statusText": "Checked Out",
    "papId": "13m3ud7zer5o7uge5yle",
    "accessType" : "PROGRAMMATIC"
}

2.3 Checking out a profile with Step Up Verification enabled

You get the following response after checking out a profile for which Step Up verification is enabled:

{
  "message": "Step up authentication required for {action} on consumer {consumer} - resource {resource}",
  "errorCode": "PE-0028",
  "extraInfo": {
    "factor": "TOTP",
    "alwaysPrompt": false
  }
}

To complete the Step Up verification with TOTP, use the following API:

Request Example

An example POST request for checking out user profiles is shown here:

{
    "otp": "858521"
}

Response Example

{
    "result": "SUCCEEDED"
}

3. Tokens of a Checked-out Profile

The GET method returns the tokens associated with a checked-out profile for the supported applications. The transactionID generated by the checkout API is required as the input. This API is supported by AWS, Azure, and GCP applications.

Request Example

An example GET request for retrieving the tokens associated with checked-out user profiles is shown here:

curl command - curl --location --request GET '{{url}}/api/access/{{txID}}/tokens' \
--header 'Authorization: TOKEN {{token}}'

Response Example 

An example response of the GET request for retrieving the tokens associated with checked-out user profiles is shown here:

{
    "accessKeyID": "AAAA",
    "secretAccessKey": "BBB",
    "expirationTime": "2020-10-14T09:44:12Z",
    "sessionToken": "CCCC"
}

4. Console Access URL of a Checked-out Profile

The GET method returns the console access URL for the checked-out profile. The transactionID generated by the Checkout API is required to get the URL.

Request Example

An example GET request for retrieving console access URL for the checked-out user profile is shown here:

curl --location --request GET '{{url}}/api/access/{{txID}}/url' \
--header 'Authorization: TOKEN {{token}}'

Response Example 

An example response of the GET request for retrieving console access URL for the checked-out user profile is shown here:

{
    "url": "https://signin.aws.amazon.com/federation?Action=login&SigninToken=AAAA"
}

5. Check-in a Profile

The PUT method can be used to check-in the user profile that was checked out using the Checkout API. If a profile is not checked in at the end of its expiry, the application automatically checks in the profile. The transactionID that was generated during check-out is required as the input.

Check-in only the specified access by using the following request:

Request Example

An example PUT request for checking-in the checked-out user profile is shown here:

curl --location --request PUT '{{url}}/api/access/{{txID}}?type=API' \
--header 'Authorization: TOKEN {{token}}'

Response Example 

An example response of the PUT request for checking-in the checked-out user profile is shown here:

{
    "accessStatusId": 13164,
    "userId": 67,
    "transactionId": "smith-3424rmyuw7ml1rnco24wcym",
    "expiration": "2020-10-14T09:44:12Z",
    "checkedOut": "2020-10-14T08:44:12Z",
    "checkedIn": "2020-10-14T08:50:22Z",
    "currentExtensionIndex": 0,
    "environmentId": "1111",
    "status": "checkedIn",
    "statusText": "Checked In",
    "papId": "13m3ud7zer5o7uge5yle"
}

6. Frequently-used profiles

This API returns all the frequently-used profiles for the logged-in user.

Request Example

An example GET request for retrieving all the frequently-used profiles for the logged-in user is shown here:

curl --location --request GET '{{url}}/api/access/frequently-used' \
--header 'Authorization: TOKEN {{token}}'

Response Example 

An example response of the GET request for retrieving all the frequently-used profiles for the logged-in user is shown here:

[
    {
        "appContainerId": "40bab4bsd246u7y55duf",
        "environmentId": "951817868444",
        "papId": "mrffc41j3jljd5z9s6vu",
        "frequency": 11,
        "myAccessDetails": {
            "checkOutTime": "2021-02-26T04:29:52Z",
            "checkInTime": "2021-02-26T04:48:54Z"
        }
    }
]

7. Favorite profiles

This API returns all profiles marked as favorites for the logged-in user.

Request Parameters

The request parameters used in this method are shown in the following table:

Request Example

An example GET request for retrieving all profiles marked as favorites for the logged-in user is shown here:

curl --location --request GET '{{url}}/api/access/favorites/accessTypeRequired=true' \
--header 'Authorization: TOKEN weWJUHTaim+dgnXmiE0/0L2KyOLQAH6B8c/F2DBGBJE='

Response Example 

An example response of the GET request for retrieving all profiles marked as favorites for the logged-in use is shown here:

[
    {
        "favoriteId": "ie9fofftduvthzxpwd2r",
        "userId": "947LkZn6Hu9rf02JmwLg",
        "papId": "u837wrygsk0ix4bvf0n4",
        "appContainerId": "3uwecl7t6uzbf0l03t1z",
        "environmentId": "546836430071",
        "accessType" : "PROGRAMMATIC",
        "myAccessDetails": {
            "checkOutTime": "2021-03-31T04:40:12Z",
            "checkInTime": "2021-04-01T06:03:07Z"
        }
    }
]