Using a Service Account With the Flexera One APIs

Use the following steps to create a service account for an application that will connect to Flexera One’s APIs. Service accounts are complimentary to refresh tokens. They can be given lesser privileges and can be decoupled from any specific user.

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.

Service Account Overview

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

Creating a Service Account 

Service Account Create API

Service Account API Documentation 

Grant roles/permissions using Access Rule API

Access Rule API Documentation 

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

1. Get an access token by calling the token API— including the ClientID and clientSecret in the API call. For more information, see Creating a Service Account.
2. Make an API call to Flexera API, including the access token.
3. When the access token expires, return to Step 1 to get a new access token.

Service Account APIs

Service Account APIs 

Access Rule APIs

Access Rule APIs 

Creating a Service Account

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.