API Access Keys and Tokens

The Lacework API uses token authentication to authorize API requests. To use bearer tokens, create an API access key with a generated secret in the Lacework Console. You can then use the key and secret to get temporary access (bearer) tokens to authenticate requests to the API.

To create API access keys, you must be an administrator in the Lacework Console. Each user is limited to 20 API keys. An API access key doesn't expire but it can be disabled or deleted. After creating a key, it should be downloaded and securely stored.

For more information about creating and using access (bearer) tokens for accounts in a Lacework organization, see Role-Based API Authentication for Organizations.

Create API Keys

You can create an API access key in the Lacwework Console from the Settings > Configuration > API keys page.

For details on creating a key in the Lacework Console, see API Access Keys.

Temporary API Tokens

After creating an access key, administrators can generate temporary API access (bearer) tokens that clients and client applications can use to access the Lacework API. Use the Lacework API's POST api/v2/access/tokens operation to create temporary API access (bearer) tokens.

Method	POST
URL	https://YourLacework.lacework.net/api/v2/access/tokens
Headers	X-LW-UAKS:YourSecretKey Content-Type:application/json
Request Body	{ "keyId": YourAccessKeyID", "expiryTime": 3600 }

Replace YourSecretKey, YourAccessKeyID, and YourLacework with your values.

The expiryTime parameter is optional. If omitted from the request body, expiryTime defaults to 3600 seconds. The maximum expiryTime allowed is one day, 86400 seconds.

For more information about creating and using access (bearer) tokens for accounts in an organization, see Role-Based API Authentication for Organizations.

Generate Token Using Curl

To generate the API access token using curl, use a command in the following form:

curl -H "X-LW-UAKS:<YOUR_SECRET_KEY>" -H "Content-Type: application/json" -X POST -d '{"keyId": "<YOUR_ACCESS_KEY_ID>", "expiryTime":3600}' https://<YOUR_LACEWORK_URL>.lacework.net/api/v2/access/tokens

To set a expiry time (other than the default), specify the expiryTime value in the body of the request:

curl -H "X-LW-UAKS:<YOUR_SECRET_KEY>" -H "Content-Type: application/json" -X POST -d '{"keyId": "<YOUR_ACCESS_KEY_ID>", "expiryTime":3600}' https://<YOUR_LACEWORK_URL>.lacework.net/api/v2/access/tokens --data-raw '{ "keyId":"<YOUR_ACCESS_KEY_ID>", "expiryTime": 86400 }'

Replace YOUR_SECRET_KEY, YOUR_ACCESS_KEY_ID, and YOUR_LACEWORK_URL with your values.

Generate Token Using Postman

To generate the API access token using Postman, construct your request.

Response Body

The response body returns the token and expiryTime.

{
  “token”: “string”,
  “expiresAt”: “datetime”
}

Role-Based API Authentication for Organizations

An organization contains the account that was used to enroll in the organization and possibly multiple sub-accounts.

When running a Lacework API operation on a sub-account in an organization, the login account that created the secret key and access key ID determines the role permission.

• If you call the POST /api/v2/access/tokens operation with a secret key and access key ID created by an organization admin, the returned access (bearer) token (OrgAdminToken) provides organization admin privileges.
• If you call the POST /api/v2/access/tokens operation with a secret key and access key ID created by an account admin, the returned access (bearer) token (AccountAdminToken) provides admin privileges for any organization sub-accounts where that admin is an account admin.
• If you call the POST /api/v2/access/tokens operation with a secret key and access key ID created by an account user, the POST /api/v1/access/tokens operation does not return an access (bearer) token because an account user does not have permission to create an access (bearer) token.

To learn more about Lacework organizations, see Organization Overview.

Overview of Lacework API Operations with an Organization

You can call Lacework API operations for an organization by specifying the Lacework organization URL.

The account that was used to initially enroll in the organization has its Lacework URL used for the organization and all sub-accounts in the organization. To access the Lacework API for an organization, specify the URL for the organization, for example: organization.lacework.net. A sub-account is any account besides the one used for organization enrollment.

The following sections discuss how to call Lacework API operations by using the OrgURL and passing in the Account-Name header. Two methods are available:

• Use an organization admin token
• Use an account admin token

The following sections call the Lacework organization URL OrgURL and the account name OrgAccount.

Use an Organization Admin Token

If an organization admin calls the POST /api/v2/access/tokens operation, the returned access (bearer) token provides organization administrator privileges. (The following examples call this bearer token OrgAdminToken.) The role associated with the OrgAdminToken defines the data that Lacework API operations can access. By specifying the OrgAdminToken, you can access the data for any account in the organization. Each API operation, however, can return data about only one account.

Pass in the Account-Name header and specify the OrgURL and OrgAdminToken. If you don't pass in the Account-Name, Lacework accesses the account that the token was created in.

For example, to access OrgAccount data, specify the following curl command:

curl "https://OrgURL/api/v2/CloudAccounts" -H "Authorization: Bearer OrgAdminToken" --header "Account-Name: OrgAccount"

For example, to access SubAccount1 data, specify the following curl command:

curl "https://OrgURL/api/v2/CloudAccounts" -H "Authorization: Bearer OrgAdminToken" --header "Account-Name: SubAccount1"

For example, to access SubAccount2 data, specify the following curl command:

curl "https://OrgURL/api/v2/CloudAccounts" -H "Authorization: Bearer OrgAdminToken" --header "Account-Name: SubAccount2"

Additionally, you can pass in the Org-Access header to access organization-level data.

For example, specify the following curl command:

curl "https://OrgURL/api/v2/CloudAccounts" -H "Authorization: Bearer OrgAdminToken" --header "Org-Access: true"

Use an Account Admin Token

If an account admin for a sub-account within an organization calls the POST /api/v2/access/tokens operation, the returned access (bearer) token provides admin privileges for sub-accounts where that admin is an account admin. (The following examples call this bearer token AccountAdminToken.) The role associated with the AccountAdminToken defines the data that Lacework API operations can access.

For example, when you call the GET /api/v2/CloudAccounts API operation with the AccountAdminToken, if the admin that generated the access (bearer) token has admin access to the specified account, all the integrations and alert channels for the specified account are returned.

Pass in the Account-Name header and specify the OrgURL and AccountAdminToken. In the following examples, the account admin has admin access to SubAccount1 and SubAccount2 in the organization.

For example, to access SubAccount1 data, specify the following curl command:

curl "https://OrgURL/api/v2/CloudAccounts" -H "Authorization: Bearer AccountAdminToken" --header "Account-Name: SubAccount1"

For example, to access SubAccount2 data, specify the following curl command:

curl "https://OrgURL/api/v2/CloudAccounts" -H "Authorization: Bearer AccountAdminToken" --header "Account-Name: SubAccount2

note

You cannot access OrgAccount data with an AccountAdminToken because it does not have permission to access organization-level data.