Authentication
The JupiterOne APIs use a Bearer Token for authentication. Include the API key in the header as a Bearer Token. You also need to include JupiterOne-Account as a header parameter. You can find the Jupiterone-Account value in your account by running the following J1QL query:
FIND jupiterone_account as a return a._accountId
API Keys
API keys enable users to use the J1 APIs in queries and with integrations. You can enable the use of API keys for a group of users and create API keys for your organization account. This can be done both through our GraphQL public API and the JupiterOne dashboard.
Create API Keys Using the GraphQL API
You can use GraphQL queries to create account-level API keys.
To create an account-level API key, enter:
POST `https://graphql.us.jupiterone.io/`
mutation CreateToken($token: TokenInput!) {
createToken(token: $token) {
token
id
name
category
policy
revoked
createdAt
expiresAt
__typename
}
}
{
"variables": {
"token": {
"name": "Token Name",
"category": "tags",
"policy": "{\n\t\"permissions\": [{\n\t\t\"effect\":\"ALLOW\",\n\t\t\"actions\":[\"dashboard:View\" ],\n\t\t\"resources\": [ \"dashboard:123456\" ]\n\t}]\n}"
}
}
}
Wildcards are not supported for account-level API tokens.
The policy variable is a JSON object formatted as follows:
{
"permissions": [
{
"effect": "ALLOW",
"actions": ["dashboard:View"],
"resources": ["dashboard:123456"]
}
]
}
The effect parameter is ether ALLOW or DENY and is case-sensitive. Currently, JupiterOne only supports fully-qualified actions and resources or the wildcard *.
Supported actions include:
"compliance:GetStandard",
"compliance:GetSummary",
"dashboard:View",
"persister:GetEntityRawData",
"persister:Synchronize",
"query:GetAccountEntity",
"query:ReadGraphData",
"settings:GetSettings",
"parameters:GetParameter",
"parameters:GetParameterList",
"parameters:SetParameter",
"parameters:DeleteParameter"
"*" // All actions
Supported resources include:
"account:<resourceId>",
"api:<resourceId>",
"compliance-standard:<resourceId>",
"dashboard:<resourceId>",
"entity:<resourceId>",
"integration:<resourceId>",
"powerup:<resourceId>",
"settings-category:<resourceId>",
"parameter:<resourceId>"
"*" // All resources
The action query:ReadGraphData may be constrained by a condition. For the policy to allow access to a graph object, that graph object must have the properties specified in the condition and those properties must have the values specified in the condition. These J1QL Query Policies must include effect: "ALLOW"; actions: ["ReadGraphData"] (or actions: ["*"]); and resources: ["*"]. In addition, their conditions block must contain an object of the stringEquals comparison. For example, this policy only allows its user to query for graph objects that have the property _type equal to github_repo:
{
"permissions": [
{
"effect": "ALLOW",
"actions": ["query:ReadGraphData"],
"resources": ["*"],
"condition": {
"stringEquals": {
"_type": "github_repo"
}
}
}
]
}
Revoke Account-Level API Keys
To revoke an account-level key, enter:
POST `https://graphql.us.jupiterone.io/`
mutation RevokeToken($id: String!) {
revokeToken(id: $id) {
token
id
name
category
policy
revoked
createdAt
expiresAt
__typename
}
}
{
"variables": {
"id": "<tokenId>"
}
}
Creating API Keys within the dashboard
In addition to creating API keys via our GraphQL API, they can be created within the dashboard as outlined below.
You must have the Administrator permission to enable API key access.
Enable User-Level API Key Access
Before creating Account-level API keys, it will be necessary to to enable API key access for a group of users:
- Go to Settings > Users & Access.
- Select the group for whom you want to enable API access.
- Select API Key Management.
An API key icon appears in the My Profile view for each user in the group that has API key access.
Create Account-Level API Keys
You can manage user-level keys in the Account Management page. You must have administrator permissions to make changes to account-level API keys.
To generate a new API key or manage existing API keys:
- Log in to the account you want to manage.
- Go to Settings > Account Management.
- In the left panel, click the key icon.
- In the User API Keys page, click Add.
- In the API Keys modal, enter the name of the key and the number of days before it expires, and click Create.
To revoke an API key, in the User API Keys page, go to the key you want to revoke and click the trash icon.
API Key Permissions Policy
You must set a permission policy in JSON for account-level API keys, similar to an IAM policy in AWS. The following is an example of a full control policy:
{
"permissions": [
{
"effect": "ALLOW",
"actions": [
"*"
],
"resources": [
"*"
]
}
]
}
J1 supports the creation of * policies that permit all actions or resources:
{
"permissions": [
{
"effect": "ALLOW",
"actions": [
"*"
],
"resources": [
"*"
]
}
]
}
{
"permissions": [
{
"effect": "ALLOW",
"actions": [
"query:ReadGraphData"
],
"resources": [
"*"
]
}
]
}
{
"permissions": [
{
"effect": "ALLOW",
"actions": [
"*"
],
"resources": [
"*"
]
},
{
"effect": "DENY", /// Deny only ReadGraphData
"actions": [
"query:ReadGraphData"
],
"resources": [
"*"
]
}
]
}
Create Integration API Keys
Integration API keys can only be used to synchronize data within a particular integration's scope and cannot be used to read the graph or perform any other action in the system. This can be useful for local development and running the integration in your own infrastructure.
You must have administrator permissions to be able to create keys and the selected integration must have at least one configuration.
To create an Integration API key:
- From the top navigation of the J1 Search homepage, select Integrations.
- Select the integration and then the instance for which you want to create an API key.
- Select the API Keys tab and then click New API Key.
- When prompted, click Create again to confirm your action.
The key is now available for you to use to synchronize data in this integrations.
To delete the API key at any time, click Revoke.