Using a Service Account With the Flexera One APIs
Create a distinct service account for each application you wish to connect to Flexera One.
The following sections are provided:
• | Service Account Overview—Provides a high-level overview of creating service accounts and links to applicable documentation. |
• | Creating a Service Account—Provides a step-by-step procedure for creating service accounts. |
• | Example of Using a Service Account—Provides a step-by-step example for using a service account client. |
The following table provides a high-level overview with references for how to create and use service accounts. A more detailed step-by-step procedure is provided in Creating a Service Account
Topic |
Documentation Link and Notes |
|||||||||
How to create a service account |
||||||||||
Service Account Create API |
||||||||||
Grant roles/permissions using Access Rule API |
||||||||||
Create a service account client |
Service Account Client API Documentation Note:The service account client consists of a clientID and clientSecret. These values should be stored securely for use by the customer application. |
|||||||||
How to access Flexera One APIs using Service Account |
|
|||||||||
Service Account APIs |
||||||||||
Access Rule APIs |
This section provides a detailed step-by-step procedure for how to create a service account.
Important:In the following procedure, you will need to use the api.flexera endpoint that matches the environment that your org is located in (North America—api.flexera.com, EU—api.flexera.eu, and APAC—api.flexera.au). The examples shown here use North America’s endpoint, api.flexera.com. Update this URI accordingly.
To create a service account
1. | Refer to the Flexera One API Authentication page on developer.flexera.com to do the following: |
a. | Get an API Refresh Token. |
b. | Generate an access token using the refresh token. Store this token in a variable named USER_TOKEN. |
2. | Identify the organization that the service account will exist in and save this number in a variable named ORG_ID. |
3. | Use the Identity and Access Management API to create a service account. Consider the following: |
• | Use a name appropriate for the application which will use the service account. |
• | Optionally, provide a description to describe the use of the service account. |
• | Notice the service account’s ID is returned in the location header (in this example, 2263). Keep this ID at hand. |
curl -X POST -s -i https://api.flexera.com/iam/v1/orgs/$ORG_ID/service-accounts \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $USER_TOKEN" \
-d '{"name": "my application", "description": "Reads data from Flexera One APIs"}'
HTTP/2 201
...
location: /iam/v1/orgs/1105/service-accounts/2263
...
4. | Show the service account. Refer to the Service Account API Get by ID documentation for more information. |
curl -s https://api.flexera.com/iam/v1/orgs/$ORG_ID/service-accounts/2263 \
-H "Authorization: Bearer $USER_TOKEN" | jq
{
"id": 2263,
"name": "my application",
"description": "Reads data from Flexera One APIs",
"createdBy": 121456,
"createdAt": "2023-07-10T20:28:48.531479Z",
"updatedAt": "2023-07-10T20:28:48.531479Z",
"kind": "iam#service-account",
"ref": "iam#service-account:2263"
}
5. | Assign role(s) to the service account. The service account should be given the least permission possible to accomplish its tasks. Do the following: |
a. | Review the roles in the organization. Refer to the Access Rule API Role documentation for more information. |
curl -s https://api.flexera.com/iam/v1/orgs/$ORG_ID/roles \
-H "Authorization: Bearer $USER_TOKEN" | jq
[
...
{
"id": 678907,
"createdAt": "2020-03-20T16:18:56.542732Z",
"name": "iam_admin",
"capability": "iam",
"privileges": [
...
"iam:user:index",
"iam:user:show"
],
"kind": "iam#role"
},
...
]?
b. | Identify the name of the role that should be granted (iam_admin is used in this example). See Flexera One Roles for more information on the roles and their descriptions. |
c. | Grant the roles to the service account. Repeat this step for any number of roles which must be granted to the service account. See the following Access Rule API Role documentation for more information. |
Note:Use the ref format shown here (ref::::iam:service-account:2263) in this API call. See Resource References for more information.
curl -s https://api.flexera.com/iam/v1/orgs/$ORG_ID/access-rules/grant -X PUT -i \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $USER_TOKEN" \
-d '{
"role": {
"name": "iam_admin"
},
"subject": {
"ref": "ref::::iam:service-account:2263"
}
}'
HTTP/2 204
...
6. | Use the Identity and Access Management API to create a service account client. The client contains the service account’s credentials. |
curl -s https://api.flexera.com/iam/v1/orgs/$ORG_ID/service-accounts/2263/clients \
-H "Authorization: Bearer $USER_TOKEN" -X POST
{"clientId":"<clientId>","clientSecret":"<clientSecret>","createdBy":121456,"createdAt":"2023-07-10T20:50:41.195629Z","kind":"iam#service-account-client"}
7. | The clientId and clientSecret must be stored securely, as they are sensitive. Anyone with access to these credentials will have access to your organization. |
Example of Using a Service Account
This section provides an example of using a service account after it is created. In this procedure, the application needs to use the clientId and clientSecret. Those values should be securely loaded into the application, or stored in a place where the application can securely access them
Important:In the following procedure, you will need to use the api.flexera endpoint that matches the environment that your org is located in (North America—api.flexera.com, EU—api.flexera.eu, and APAC—api.flexera.au). The examples shown here use North America’s endpoint, api.flexera.com. Update this URI accordingly.
To use a service account client
1. | Run the application. The remaining API calls are performed by the application, not the user setting up the service account. However, for this demonstration, we will perform them with curl. |
2. | Get an access token. The access token is a temporary credential (see from the response that the access token expires in 3600 seconds or 1 hour). See the Flexera One API Authentication page on developer.flexera.com for details. |
curl -X POST https://login.flexera.com/oidc/token \
-H "Content-Type: application/x-www-form-urlencoded" \
-d "client_id=<clientId>&client_secret=<clientSecret>&grant_type=client_credentials" | jq
{
"access_token": "<accessToken>",
"expires_in": 3600,
"token_type": "Bearer"
}
3. | Use the access token to call Flexera One APIs. In this example, we list the users in the org, which is permitted for the role we granted our service account (iam_admin). |
curl -s https://api.flexera.com/iam/v1/orgs/$ORG_ID/users \
-H "Authorization: Bearer $ACCESS_TOKEN" | jq .
{
"values": [
{
"kind": "iam#user",
"ref": "iam#user:111222333",
"id": 111222333,
"email": "JDoe@flexera.com",
"firstName": "Jane",
"lastName": "Doe",
"createdAt": "2022-11-14T15:29:45.191995Z",
"updatedAt": "2023-06-28T20:40:14.999786Z",
"lastUILogin": "2023-06-28T20:40:15.705245Z",
"lastAPILogin": "2023-01-23T19:51:56.346877Z"
},
...
]
}
4. | After the access token is expired (or is nearing expiry), repeat the previous /oidc/token API call (step 9) to get a new access token. The access token is a sensitive credential, so the application should not expose the value to be read by any user. |
Note:The application can continue using the access token to accomplish its tasks, replacing its token whenever necessary.