FlexNet Operations Access Tokens API (2024.09)

Download OpenAPI specification:Download

FlexNet Operations Access Tokens API

Access Token Controller

A REST Controller for creating access tokens to be used as bearer authentication tokens for calling FlexNet Operations APIs (SOAP and REST). This REST web service also supports reading, updating, searching, rotating, and deleting tokens.

FlexNet Operations uses different token types to manage different access levels and operations:

  • NORMAL tokens can be requested by any FlexNet Operations user to authenticate themselves at a FlexNet Operations API.
  • IMPERSONATED tokens can be requested by a privileged user for use by other FlexNet Operations users.

To create and manage IMPERSONATED tokens, users require the Create Impersonated Token permission and a Manage Users permission.

Create an access token

Use this API to create an access token.

The response includes the token value. This is the only time the token value is displayed. The value must be included as a Bearer token in the Authorization HTTP header for authorization requests.

Typically, an access token has the following attributes:

  • Token name—Must be unique and 5 - 25 characters long.
  • Expiry string—The token lifetime. Format: *y *M *d *h *m, where y=years, M=months, d=days, h=hours, m=minutes (case sensitive), and * representing any number.
  • Token type—Valid values: NORMAL | IMPERSONATED.
  • Token description—Mandatory for IMPERSONATED tokens.
  • Username—User name of the user on whose behalf the token is created. Mandatory for IMPERSONATED tokens.

When a username is provided for the creation of a NORMAL token, that username is ignored when calling an API. Instead, the user calling the API is authenticated.

Request
Request Body schema: application/json
required

reqBody

expiryStr
required
string

Lifetime of the token as specified when the token was created.
Format: *y *M *d *h *m, where y=years, M=months, d=days, h=hours, m=minutes (case sensitive), and * representing any number.

tokenDescription
string

Mandatory for IMPERSONATED tokens; optional for NORMAL tokens. For IMPERSONATED tokens, use this field to capture the impersonation reason.

tokenName
required
string

Name of the token, must be 5 - 25 characters long.
The following characters are not supported:
* < > + $ ? . ^ | % ] \\\\ (four consecutive back slashes are not allowed)
HTML tags that may indicate an XSS attack will be rejected.

tokenType
required
string

Specify the token type.
NORMAL tokens can be requested by any FlexNet Operations user.
IMPERSONATED tokens can be requested by a privileged user on behalf of another FlexNet Operations user.

Enum: "NORMAL" "IMPERSONATED"
username
required
string

The user for whom the token is created. Usually this is specified as an email address. This field is mandatory for IMPERSONATED tokens.

Responses
200

OK

post/uar/v1/token
Request samples
application/json
{
  • "expiryStr": "string",
  • "tokenDescription": "string",
  • "tokenName": "string",
  • "tokenType": "NORMAL",
  • "username": "string"
}
Response samples
application/json
{
  • "responseObject": {
    },
  • "statusMessage": "string"
}

Verify an access token

Use this API to very if a token is valid. Pass the token value in the request body. The response shows if the token is valid, along with information about the token.

Only the token creator can verify IMPERSONATED tokens. If you do not have the Create Impersonated Token and relevant Manage Users permissions, the API returns obfuscated values.

Request
Request Body schema: application/json
required

accessToken

accessToken
required
string

The value of the access token that should be verified.

Responses
200

OK

post/uar/v1/token/verification
Request samples
application/json
{
  • "accessToken": "string"
}
Response samples
application/json
{
  • "responseObject": {
    },
  • "statusMessage": "string"
}

Get details of access token

Use this API to fetch the details of an access token identified by its name.

Request
path Parameters
tokenName
required
string

The name of the token for which you want to retrieve details (case sensitive).

Responses
200

OK

get/uar/v1/token/{tokenName}
Response samples
application/json
{
  • "responseObject": {
    },
  • "statusMessage": "string"
}

Update an access token

Use this API to update some of the attributes of a specified access token. Specify the name of the token that you want to update in the path (case sensitive).

In the request body, specify the new values. You can update the following token attributes:

  • tokenName—Must be 5 - 25 characters long.
  • tokenDescription—For IMPERSONATED tokens this field should state the impersonation reason.
  • expiryStr—Must not be in the past. Format:*y *M *d *h *m, where y=years, M=months, d=days, h=hours, m=minutes (case sensitive), and * representing any number.

Only the token creator or another privileged user can update an IMPERSONATED token. You cannot edit an expired token or set the token expiry to a time in the past.

Request
path Parameters
tokenName
required
string

Name of the token to be updated (case sensitive).

Request Body schema: application/json
required

reqBody

expiryStr
required
string

Lifetime of the token as specified when the token was created.
Format: *y *M *d *h *m, where y=years, M=months, d=days, h=hours, m=minutes (case sensitive), and * representing any number.

tokenDescription
string

Mandatory for IMPERSONATED tokens; optional for NORMAL tokens. For IMPERSONATED tokens, this field should capture the impersonation reason.

tokenName
required
string

The name of the token.

Responses
200

OK

put/uar/v1/token/{tokenName}
Request samples
application/json
{
  • "expiryStr": "string",
  • "tokenDescription": "string",
  • "tokenName": "string"
}
Response samples
application/json
{
  • "body": { },
  • "statusCode": "100",
  • "statusCodeValue": 0
}

Delete an access token

Use this API to delete an access token. Pass the name of the token to be deleted as a path parameter. The token name is case sensitive.

A deleted token can no longer be used to access the APIs.

Only the token creator can delete a token; this means that only users with the Create Impersonated Token and relevant Manage Users permission can delete IMPERSONATED tokens.

Request
path Parameters
tokenName
required
string

The name of the token to be deleted (case sensitive).

Responses
200

OK

delete/uar/v1/token/{tokenName}
Response samples
application/json
{
  • "body": { },
  • "statusCode": "100",
  • "statusCodeValue": 0
}

Rotate an access token

Token rotation means that a token's value is changed, but no other properties. Pass the name of the token to be rotated as a path parameter. The token name is case sensitive.

The response contains the new token value. Make a note of the token value; this is the only time that the new value is displayed.

It is recommended to frequently rotate access tokens, but care should be exercised to not break any integrations you may have.

Request
path Parameters
tokenName
required
string

The name of the access token to be rotated (case sensitive).

Responses
200

OK

post/uar/v1/token/{tokenName}/rotation
Response samples
application/json
{
  • "responseObject": {
    },
  • "statusMessage": "string"
}

List non-expired access tokens

Use this API to get a list of all non-expired access tokens for a specified user.
You must specify either the username or the tokenCreator parameter as search criteria.
If you pass values for both parameters in the same request, the API returns a list of all non-expired tokens that match both parameters.
If you do not have the Create Impersonated Token and relevant Manage Users permissions, the API returns obfuscated values.

Tip: If you want a more fine-grained search, use /tokens/search.

Request
query Parameters
username
string

The email address of the user for whom tokens should be listed (case sensitive). This is the user for whom the token was created.

tokenCreator
string

The email address of the token creator for whom tokens should be listed (case sensitive). This is the user who created tokens on another user's behalf.

page
integer <int32>

Retrieves a specific page. Must be a number (starting from 0).

pageSize
integer <int32>

Specifies how many tokens per page should be returned. Must be a number.
Tip: Use the /tokens/count API to determine the total number of records for a specified user.

Responses
200

OK

get/uar/v1/tokens
Response samples
application/json
{
  • "responseObject": [
    ],
  • "statusMessage": "string"
}

Get count of non-expired access tokens

Use this API to get a count of all non-expired access tokens for a specified user.
You must specify either the username or the tokenCreator parameter as search criteria.
Tip: Use this API to specify values for the pagination parameters of the /tokens API.

Request
query Parameters
username
string

The email address of the user for whom the token count should be returned (case sensitive). This is the user for whom the tokens were created.

tokenCreator
string

The email address of the token creator for whom the token count should be returned (case sensitive). This is the user who created tokens on another user's behalf.

Responses
200

OK

get/uar/v1/tokens/count
Response samples
application/json
{
  • "responseObject": 0,
  • "statusMessage": "string"
}

Search for non-expired access tokens

Get a list of all non-expired access tokens that match specified search criteria.

You must specify at least one of the following search criteria. If you pass multiple parameters as search criteria, the API returns non-expired tokens that match all parameters.

  • tokenName—Search by token name. Use an asterisk (*) as placeholder for partial searches.
  • tokenType—Either NORMAL or IMPERSONATED. If not specified, all token types will be returned.
  • username—The email address of the user for whom the token was created.
  • tokenCreator—The email address of the user who created the token on another user's behalf. For NORMAL tokens, username and tokenCreator must be the same. For IMPERSONATED tokens, the user firing this query must have the Create Impersonated Token permission and a Manage Users permission.
  • expiresBefore—Specify to filter for tokens that expire before a specified interval. Can be used in conjunction with the expiresLaterThan parameter to filter for a given time range. In that case, expiresBefore must be greater than expiresLaterThan.
  • expiresLaterThan—Specify to filter for tokens that expire after a specified interval. Can be used in conjunction with the expiresBefore parameter to filter for a given time range. In that case, expiresLaterThan must be less than expiresBefore.
  • issuedBefore—Specify to filter for tokens that were issued before a specified interval.

If you do not have permission to view a given token, its details are returned as masked entries.

The format for expiresBefore, expiresLaterThan and issuedBefore is *y *M *d *h *m, where y=years, M=months, d=days, h=hours, m=minutes (case sensitive), and * representing any number.

In addition to the search criteria above you must also specify the following parameters:

  • page—The number of the page to be returned (zero based).
  • pageSize—The number of records returned per page.

Request
Request Body schema: application/json
required

searchToken

tokenCreator
string

The email address of the user who created tokens on another user's behalf (case sensitive).

expiresBefore
string

Gets tokens that expire before a specified interval. If used in conjunction with expiresLaterThan, must be greater than expiresLaterThan. Use the format 5y 6M 4d 3h 5m, where y=years, M=months, d=days, h=hours, m=minutes (case sensitive).

expiresLaterThan
string

Gets tokens that expire after a specified interval. If used in conjunction with expiresBefore, must be less than expiresBefore. Use the format 5y 6M 4d 3h 5m, where y=years, M=months, d=days, h=hours, m=minutes (case sensitive).

issuedBefore
string

Gets tokens that were issued before a specified interval. Use the format 5y 6M 4d 3h 5m, where y=years, M=months, d=days, h=hours, m=minutes (case sensitive).

page
required
integer <int32>

The number of the page to be returned (zero based).

pageSize
required
integer <int32>

The number of records returned per page.

tokenName
string

The name of the token. Use an asterisk (*) as placeholder for partial searches.

tokenType
string

Type of the token.

Enum: "NORMAL" "IMPERSONATED"
username
string

The email address of the user for whom the token was created (case sensitive).

Responses
200

OK

post/uar/v1/tokens/search
Request samples
application/json
{
  • "tokenCreator": "string",
  • "expiresBefore": "string",
  • "expiresLaterThan": "string",
  • "issuedBefore": "string",
  • "page": 0,
  • "pageSize": 0,
  • "tokenName": "string",
  • "tokenType": "NORMAL",
  • "username": "string"
}
Response samples
application/json
{
  • "responseObject": {
    },
  • "statusMessage": "string"
}