API Access Key for Application

Access Key Usage

Access keys can be used in the following scenarios:

Server-to-Server Requests: Sign the client IP address in server-to-server requests. The request is signed with the Signature HTTP header.
Token Exchange: Pass the access key in the Authorization: Bearer HTTP header when using the exchangeJwt method.
User Schema Retrieval: When an access key is provided via Authorization: Bearer:
- User permissions can be requested even if the JWT has expired.
- User roles can be requested without any JWT.

Retrieve, Create, and Delete Access Key

Retrieves the list of access keys, creates a new one, or deletes an existing one for the specified application.

Access Requirements

The request author must have secret_data.application.canCreateJwt or projectID/applications/appID/app.can_manage_app_api_keys.

Note

The maximum number of access keys per application is 2. The key hash is shown only once, upon successful creation.

Request

POST /api/permissions/accessKey

Warning

Passing jwt, factor, and service_jwt in the request body is deprecated. Use the corresponding HTTP headers instead.

jwt string required 

User’s JWT token.
factor string conditionally required 

User device factor. Required if service_jwt is not provided.
service_jwt string conditionally required 

Service JWT. Required if factor is not provided.
application_id string or integer required 

ID of the application.
action string required 

Action to perform. Allowed values: "get", "save", "delete".
data object optional 

Required for "save" and "delete" actions.
- comment string optional 
  
  User comment for the key. Used for "save".
- id string optional 
  
  ID of the access key to delete. Required for "delete".

Request example

POST /api/permissions/accessKey

Headers

Authorization: Bearer eyJhbGci...
Factor: ...

Body (get)

{
  "application_id": 2,
  "action": "get"
}

Body (save)

{
  "application_id": 2,
  "action": "save",
  "data": {
    "comment": "Main access key"
  }
}

Body (delete)

{
  "application_id": 2,
  "action": "delete",
  "data": {
    "id": "62750cb875621cb765dc5430"
  }
}

Response

OK

Success

status string required 
- “OK”
data object or array optional 

For "get": array of access key objects.
- id string required 
  
  Access key ID.
- application_id integer required 
  
  ID of the application the key belongs to.
- comment string required 
  
  User comment for the key.
- created string required 
  
  Creation timestamp.
- modified string required 
  
  Last modification timestamp.
- last_used string optional 
  
  Last usage timestamp. Omitted if the key has never been used.
For "save": the created access key object, including hash.
- id string required 
  
  Access key ID.
- application_id integer required 
  
  ID of the application the key belongs to.
- hash string required 
  
  The access key hash. Shown only once upon creation.
- comment string required 
  
  User comment for the key.
- created string required 
  
  Creation timestamp.
- modified string required 
  
  Last modification timestamp.
For "delete": no data returned.

Response example (get)

{
  "status": "OK",
  "data": [
    {
      "id": "62750cb875621cb765dc5430",
      "application_id": 2,
      "comment": "Main access key",
      "created": "2022-05-06 11:55:36.111 +0000 UTC",
      "modified": "2022-05-06 11:55:36.111 +0000 UTC"
    }
  ]
}

Response example (save)

{
  "status": "OK",
  "data": {
    "id": "62750cb875621cb765dc5430",
    "application_id": 2,
    "hash": "c5a78fb0...",
    "comment": "Main access key",
    "created": "2022-05-06T12:19:52.8458532Z",
    "modified": "2022-05-06T12:19:52.8458532Z"
  }
}

Response example (delete)

{
  "status": "OK"
}

ERROR

Error

status string required 
- “ERROR”
  
  Request failed.
- “LOGINERROR”
  
  Authentication error (delete action only).
error string required 

Descriptive error message.

Response example

{
  "status": "ERROR",
  "error": "access key not found"
}