Key Pairs

Table of Content:

Create key pair
Check key pair
Delete key pair
Get key pairs
Verify key pair

Create a key pair

This API endpoint creates a new API key pair and returns the key, secret, and verification code ID.

Endpoint: https://apis.threatwinds.com/api/auth/v2/keypair

Parameters

Parameter	Location	Type	Required	Description	Example
Authorization	header	string	Yes	Bearer token from an active session.
name	body	string	Yes	A descriptive name for the key pair to help you identify it later.	“My Application Key”
days	body	integer	Yes	The number of days until the key pair expires.	365

To create a key pair, use a POST request, for example:

curl -X 'POST' \
  'https://apis.threatwinds.com/api/auth/v2/keypair' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer <YOUR_BEARER_TOKEN>' \
  -H 'Content-Type: application/json' \
  -d '{
  "name": "Example",
  "days": 365
}'

Returns

A successful response will return a JSON object containing the API key, API secret, key ID, and verification code ID:

{
  "apiKey": "<YOUR_API_KEY>",
  "apiSecret": "<YOUR_API_SECRET>",
  "keyID": "5f35d2c4-5633-4b16-bbf0-5ca22ef8ea2e",
  "keyName": "Example",
  "expireAt": 1674492894,
  "verified": false,
  "verificationCodeID": "5f35d2c4-5633-4b16-bbf0-5ca22ef8ea2e"
}

Important: Store the API secret securely. It will not be displayed again.

Note: Verification codes expire after 5 minutes. A maximum of 3 attempts are allowed per code before it is invalidated. If the code expires or attempts are exhausted, create a new key pair to receive a fresh code.

Check a key pair

This API endpoint checks a key pair and returns its privileges.

Endpoint: https://apis.threatwinds.com/api/auth/v2/keypair

Parameters

Parameter	Location	Type	Required	Description
api-key	header	string	Yes	Your API key.
api-secret	header	string	Yes	Your API secret.

To check a key pair, use a GET request, for example:

curl -X 'GET' \
  'https://apis.threatwinds.com/api/auth/v2/keypair' \
  -H 'accept: application/json' \
  -H 'api-key: <YOUR_API_KEY>' \
  -H 'api-secret: <YOUR_API_SECRET>'

Returns

A successful response will return a JSON object containing information about the key pair and its associated privileges:

{
  "apiKey": "<YOUR_API_KEY>",
  "keyID": "5f35d2c4-5633-4b16-bbf0-5ca22ef8ea2e",
  "keyName": "Example",
  "expireAt": 1674492894,
  "verified": true,
  "userID": "5f35d2c4-5633-4b16-bbf0-5ca22ef8ea2e",
  "fullName": "John Doe",
  "alias": "johny",
  "roles": ["user", "users_admin"],
  "groups": ["public"]
}

Note: The verified field indicates whether the user’s identity has been verified. This can happen through document and selfie verification, admin override (PUT /admin/user/{id}/verify), or automatic verification for partner-created users. This is separate from key pair verification (which is required to use the key pair). ```

Delete a key pair

This API endpoint deletes a key pair.

Endpoint: https://apis.threatwinds.com/api/auth/v2/keypair/{id}

Parameters

Parameter	Location	Type	Required	Description	Example
Authorization	header	string	Yes	Bearer token from an active session.
id	path	string	Yes	The ID of the key pair to delete.	5f35d2c4-5633-4b16-bbf0-5ca22ef8ea2e

To delete a key pair, use a DELETE request, for example:

curl -X 'DELETE' \
  'https://apis.threatwinds.com/api/auth/v2/keypair/5f35d2c4-5633-4b16-bbf0-5ca22ef8ea2e' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer <YOUR_BEARER_TOKEN>'

Returns

A successful response will return a JSON object with a success message:

{
  "message": "acknowledged"
}

Get key pairs

This API endpoint gets all key pairs for the current user.

Endpoint: https://apis.threatwinds.com/api/auth/v2/keypairs

Parameters

Parameter	Location	Type	Required	Description
Authorization	header	string	Yes	Bearer token from an active session.

To get all key pairs, use a GET request, for example:

curl -X 'GET' \
  'https://apis.threatwinds.com/api/auth/v2/keypairs' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer <YOUR_BEARER_TOKEN>'

Returns

A successful response will return a JSON object containing an array of key pairs:

{
  "keys": [
    {
      "apiKey": "<YOUR_API_KEY>",
      "keyID": "5f35d2c4-5633-4b16-bbf0-5ca22ef8ea2e",
      "keyName": "Example",
      "expireAt": 1674492894,
      "verified": true
    },
    {
      "apiKey": "<YOUR_API_KEY>",
      "keyID": "6a2b4c5d-6e7f-8g9h-0i1j-2k3l4m5n6o7p",
      "keyName": "Another Key",
      "expireAt": 1689492894,
      "verified": false
    }
  ]
}

Warning: This endpoint returns full, unredacted API keys (apiKey field). Treat the response as a secret — do not log, cache, or display full keys in UI. For listing keypairs without exposing credentials, use the admin endpoint GET /admin/keypairs which omits plaintext keys.

Verify key pair

This API endpoint verifies a key pair using a verification code.

Endpoint: https://apis.threatwinds.com/api/auth/v2/keypair/verification

Parameters

Parameter	Location	Type	Required	Description	Example
verificationCodeID	body	string	Yes	The verification code ID received when creating the key pair.	“5f35d2c4-5633-4b16-bbf0-5ca22ef8ea2e”
code	body	string	Yes	The verification code sent to your email.	“654321”

This endpoint does not require authentication. Only the verification code and ID are needed.

Note: Verification codes expire after 5 minutes. A maximum of 3 attempts are allowed per code before it is invalidated. If the code expires or attempts are exhausted, create a new key pair to receive a fresh code.

To verify a key pair, use a PUT request, for example:

curl -X 'PUT' \
  'https://apis.threatwinds.com/api/auth/v2/keypair/verification' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{
  "verificationCodeID": "5f35d2c4-5633-4b16-bbf0-5ca22ef8ea2e",
  "code": "654321"
}'

Returns

A successful response will return a JSON object with a success message:

{
  "message": "acknowledged"
}

Error Response Headers

For responses with status codes other than 200 and 202, the following headers are included:

Header	Description
x-error	Human-readable error message describing what went wrong
x-error-id	Unique identifier for error tracking and support

Error Codes

Status Code	Description	Possible Cause
400	Bad Request	Invalid request parameters or malformed JSON
401	Unauthorized	Missing or invalid authentication credentials
403	Forbidden	Authenticated user lacks permission for this operation
404	Not Found	The requested resource does not exist
500	Internal Server Error	Server-side error; please contact support if persistent