Managing Access Keys

The Access Key is a token that you must configure on Sysdig Agents to successfully forward data from your environment to the Sysdig backend. If the access key is compromised or you have a policy to renew it, you can generate a new access key and disable the old one. You can also define additional attributes (limits, reservations, team assignment, metadata) for each Acces Key.

You need the API token from the Sysdig UI is required to use the API. For more information, see Retrieve the Sysdig API Token.

Replace the API_TOKEN with your API token in the API calls given below.

Both /api/customer and /api/customers endpoints are valid and interchangeable. However, all the examples listed here uses /api/customers in order to align with the usage.

View and Search for Access Keys

To view all the access keys for your Sysdig instance, do the following:

Issue a curl GET request against the Sysdig Monitor endpoint to retrieve all access keys:

$ curl -XGET -H 'Authorization: Bearer <API_TOKEN>' https://<HOSTNAME>/api/customers/accessKeys

You can add a GET parameter at the end of the URL in the form of parameter=value to search using the given parameter. You can combine several parameters. Wildcards are not supported. List of available parameters:

  • accessKey=<ACCESS_KEY>: The access key to search for.
  • metadata-key=<METADATA_VALUE>: The metadata key-value pair to search for. For more information, see Searching the Available Access Keys Based on Metadata.
  • enabled=<ENABLED>: Specifies that search is performed based on the enabled parameter. Allowed values are true or false
  • id=<ID>: The ID of the access key. The value must be numeric and unique.
  • limit=<LIMIT>: The limit of access keys to return. This parameter is used by the UI.
  • offset=<OFFSET>: The number of access keys to skip before beginning to return data. This parameter is used by the UI.
  • teamId=<TEAM_ID>: Specifies that the search is performed using Team ID. See Retrieving the Available Access Keys Based on Team ID).

Replace the following:

  • <API_TOKEN> with the token you retrieved.
  • <HOSTNAME> with Sysdig domain associated with your region.

The output will provide a list of the access keys in the response and indicates whether they are enabled.

{
	"customerAccessKeys": [
		{
			"id": 1234,
			"enabled": true,
			"accessKey": "12345678-1234-4321-1234-123456789000",
			"dateCreated": 5242096409000,
			"dateDisabled": null,
			"limit": null,
			"reservation": null,
			"teamId": null,
			"metadata": {}
		},
		{
			"id": 5678,
			"enabled": true,
			"accessKey": "87654321-1234-1234-1234-123456789012",
			"dateCreated": 2553849361000,
			"dateDisabled": 2553849367000,
			"limit": null,
			"reservation": null,
			"teamId": null,
			"metadata": {}
		}
	]
}

Delete an Access Key

You can delete only disabled access keys.

To delete an access key, do the following:

Issue a curl DELETE request against the Sysdig Monitor endpoint to delete the given access key:

$ curl -XDELETE -H 'Authorization: Bearer <API_TOKEN>' https://<HOSTNAME>/api/customers/accessKeys/<ACCESS_KEY>

Replace the following:

  • <API_TOKEN> with the token you retrieved.
  • <ACCESS_KEY> with the Access Key you would like to delete.
  • <HOSTNAME> with Sysdig domain associated with your region.

There is no response, only a response status 200 to confirm the action was performed successfully.

Retrieve the Access Keys

To view all the access keys assigned to a team of the user whose API token is used, do the following:

Issue a curl GET request against the Sysdig Monitor endpoint to retrieve the list of access keys:

$ curl -XGET -H 'Authorization: Bearer <API_TOKEN>' https://<HOSTNAME>/api/customers/accessKeys/forCurrentTeam

Replace the following:

  • <API_TOKEN> with the token you retrieved.
  • <HOSTNAME> with Sysdig domain associated with your region.

The output will provide a list of the access keys in the response and indicates whether they are enabled.

{
	"total": 2,
	"customerAccessKeys": [
		{
			"id": 1234,
			"enabled": true,
			"accessKey": "12345678-1234-4321-1234-123456789000",
			"dateCreated": 5242096409000,
			"dateDisabled": null,
			"limit": null,
			"reservation": null,
			"teamId": 1,
			"metadata": {}
		},
		{
			"id": 5678,
			"enabled": true,
			"accessKey": "87654321-1234-1234-1234-123456789012",
			"dateCreated": 2553849361000,
			"dateDisabled": 2553849367000,
			"limit": null,
			"reservation": null,
			"teamId": 1,
			"metadata": {}
		}
	]
}

Retrieve the Access Keys Based on Team ID

To view all of the access keys assigned to a specific team.

Issue a curl GET request against the Sysdig Monitor endpoint to retrieve the list of access keys:

$ curl -XGET -H 'Authorization: Bearer <API_TOKEN>' https://<HOSTNAME>/api/customers/accessKeys?teamId=<TEAM_ID>

Replace the following:

  • <API_TOKEN> with the token you retrieved.
  • <TEAM_ID> with the ID of an existing team.
  • <HOSTNAME> with Sysdig domain associated with your region.

The output will provide a list of the access keys in the response and indicates whether they are enabled.

{
	"total": 0,
	"customerAccessKeys": [
		{
			"id": 1234,
			"enabled": true,
			"accessKey": "12345678-1234-4321-1234-123456789000",
			"dateCreated": 5242096409000,
			"dateDisabled": null,
			"limit": null,
			"reservation": null,
			"teamId": 1,
			"metadata": {}
		},
		{
			"id": 5678,
			"enabled": true,
			"accessKey": "87654321-1234-1234-1234-123456789012",
			"dateCreated": 2553849361000,
			"dateDisabled": 2553849367000,
			"limit": null,
			"reservation": null,
			"teamId": 1,
			"metadata": {}
		}
	]
}

Search for the Access Keys Based on Metadata

To search for access keys based on the metadata, do the following:

Issue a curl GET request against the Sysdig Monitor endpoint to search based on the metadata:

$ curl -XGET -H 'Authorization: Bearer <API_TOKEN>' https://<HOSTNAME>/api/customers/accessKeys<METADATA_SEARCH>

Replace the following:

  • <API_TOKEN> with the token you retrieved.
  • <METADATA_SEARCH> with URL encoded metadata search criteria, for example ?business-unit=testUnit. Max 10 entries supported. No wildcards allowed.
  • <HOSTNAME> with Sysdig domain associated with your region.

The output will provide a list of the access keys in the response and indicates whether they are enabled.

{
	"total": 1,
	"customerAccessKeys": [
		{
			"id": 5678,
			"enabled": true,
			"accessKey": "12345678-1234-4321-1234-123456789000",
			"dateCreated": 5242096409000,
			"dateDisabled": null,
			"limit": null,
			"reservation": null,
			"teamId": null,
			"metadata": {
				"business-unit": "testUnit"
			}
		}
	]
}

Create an Access Key

To create an access key:

Issue a curl POST request against the Sysdig endpoint to generate a new access key:

$ curl -XPOST -H 'Authorization: Bearer <API_TOKEN>' <PAYLOAD> https://<HOSTNAME>/api/customers/accessKeys

Replace the following:

  • <API_TOKEN> with the token you retrieved.
  • <HOSTNAME> with Sysdig domain associated with your region.
  • <PAYLOAD> (optional) can be omitted if not required. Structure is as follows:
    -d '{
	"customerAccessKey": {
		"limit": <LIMIT>,
		"reservation": <RESERVATION>,
		"teamId": <TEAM_ID>,
		"metadata": { <METADATA> }
	}
}'
    • <LIMIT> - Maximum number of agents allowed to connect for this access key. Set to null if not required.
    • <RESERVATION> - Number of agent licenses that will ALWAYS be available to this access key. This will directly count against the max available number of licenses. Set to null if not required.
    • <TEAM_ID> - Team ID to which to assign the access key. Team ID must be valid. Set to null if not required.
    • <METADATA> - Metadata is in the form of comma separated key/value pairs. For example:
    		"environment": "testEnv",
		"business-unit": "testUnit",
		"cluster-name": "testCluster"

The output will provide the newly generated access key in the response.

{
	"customerAccessKey": {
		"id": 5678,
		"enabled": true,
		"accessKey": "87654321-1234-1234-1234-123456789012",
		"dateCreated": 2263852422114,
		"dateDisabled": null,
		"limit": null,
		"reservation": null,
		"teamId": null,
		"metadata": {}
	}
}

The access key can now be used in the Sysdig agent configuration files.

Update an Access Key

To update an access key:

Issue a curl PUT request against the Sysdig endpoint to update an existing access key:

$ curl -XPUT -H 'Authorization: Bearer <API_TOKEN>' <PAYLOAD> https://<HOSTNAME>/api/customers/accessKeys/<ACCESS_KEY>

Replace the following:

  • <API_TOKEN> with the token you retrieved.
  • <HOSTNAME> with Sysdig domain associated with your region.
  • <ACCESS_KEY> with an existing Access Key to be updated.
  • <PAYLOAD> (optional) can be omitted if not required. Structure is as follows:
    -d '{
	"customerAccessKey": {
		"limit": <LIMIT>,
		"reservation": <RESERVATION>,
		"teamId": <TEAM_ID>,
		"metadata": { <METADATA> }
	}
}'
    • <LIMIT> - Maximum number of agents allowed to connect for this access key. Set to null if not required.
    • <RESERVATION> - Number of agent licenses that will ALWAYS be available to this access key. This will directly count against the max available number of licenses. Set to null if not required.
    • <TEAM_ID> - Team ID to which to assign the access key. Team ID must be valid. Set to null if not required.
    • <METADATA> - Metadata is in the form of comma separated key/value pairs. For example:
    		"environment": "testEnv",
		"business-unit": "testUnit",
		"cluster-name": "testCluster"

The output will provide updated information for the provided access key in the response.

{
	"customerAccessKey": {
		"id": 5678,
		"enabled": true,
		"accessKey": "87654321-1234-1234-1234-123456789012",
		"dateCreated": 2263852422114,
		"dateDisabled": null,
		"limit": null,
		"reservation": null,
		"teamId": null,
		"metadata": {}
	}
}

The access key is now updated.

Disable an Access Key

To disable an existing access key:

Issue a curl POST request against the Sysdig Monitor or Secure endpoint to disable the given access key.

$ curl -XPOST -H 'Authorization: Bearer <API_TOKEN>' https://<HOSTNAME>/api/customers/accessKeys/<ACCESS_KEY>/disable

Replace the following:

  • <API_TOKEN> with the token you retrieved.
  • <HOSTNAME> with Sysdig domain associated with your region.
  • <ACCESS_KEY> with the access key that you wish to disable.
{
	"customerAccessKey": {
		"id": 5678,
		"enabled": false,
		"accessKey": "87654321-1234-1234-1234-123456789012",
		"dateCreated": 2553849361000,
		"dateDisabled": 2553849367000,
		"limit": null,
		"reservation": null,
		"teamId": null,
		"metadata": {}
	}
}

Once you disable the Sysdig access key, the agents connected with the access key will be immediately blocked from sending data to the Sysdig backend.

The agent that tries to connect with a disabled access key will be terminated.

Enable an Access Key

To enable an existing access key:

Issue a curl POST request against the Sysdig Monitor endpoint to enable the given access key.

$ curl -XPOST -H 'Authorization: Bearer <API_TOKEN>' https://<HOSTNAME>/api/customers/accessKeys/<ACCESS_KEY>/enable

Replace the following:

  • <API_TOKEN> with the token you retrieved in step 1.
  • <HOSTNAME> with Sysdig domain associated with your region.
  • <ACCESS_KEY> with the access key that you wish to disable.
  • Restart the agents for the new connection to work as expected.
{
	"customerAccessKey": {
		"id": 5678,
		"enabled": true,
		"accessKey": "87654321-1234-1234-1234-123456789012",
		"dateCreated": 2553849361000,
		"dateDisabled": null,
		"limit": null,
		"reservation": null,
		"teamId": null,
		"metadata": {}
	}
}

The agent that tries to connect with an enabled access key will be allowed to connect.