Core
API v2.x
2

createApiKey #

Creates a new API key for a user.

API keys are just authentication tokens. You can use your API key the same way you use your authentication token by adding it to the Authorization header (with the value Bearer <YourApiKeyHere>)


Query Syntax #

HTTP #

Copied to clipboard!
URL: http://kuzzle:7512/users/<userId>/api-keys/_create[?refresh=wait_for][&expiresIn=-1][&_id=null]
Method: POST
Body:
Copied to clipboard!
{
  "description": "Sigfox callback authentication api key"
}

Other protocols #

Copied to clipboard!
{
  "controller": "security",
  "action": "createApiKey",
  "userId": "mWakSm4BWtbu6xy6NY8K",
  "body": {
    "description": "Sigfox callback authentication api key"
  },

  // optional arguments
  "_id": "api-key-id",
  "expiresIn": -1,
  "refresh": "wait_for"
}

Arguments #

Optional: #

  • expiresIn: set the expiration duration (-1 by default)
    • if a raw number is provided (not enclosed between quotes), then the expiration delay is in milliseconds. Example: 86400000
    • if this value is a string, then its content is parsed by the ms library. Examples: "6d", "10h"
    • if -1 is provided, the token will never expire
  • refresh: if set to wait_for, Kuzzle will not respond until the newly created API key is indexed (default: "wait_for")
  • _id: sets the API key unique ID to the provided value, instead of auto-generating a random ID

Body properties #

  • description: token description

Response #

Returns an object containing the newly created API key:

  • _id: API key ID
  • _source: API key content
    • userId: user kuid
    • expiresAt: expiration date in UNIX micro-timestamp format (-1 if the token never expires)
    • ttl: original ttl
    • description: description
    • fingerprint: SHA256 hash of the authentication token
    • token: authentication token associated with this API key

The authentication token token will never be returned by Kuzzle again. If you lose it, you'll have to delete the API key and recreate a new one.

Copied to clipboard!
{
  "status": 200,
  "error": null,
  "controller": "security",
  "action": "createApiKey",
  "requestId": "<unique request identifier>",
  "result": {
    "_id": "api-key-id",
    "_source": {
      "userId": "mWakSm4BWtbu6xy6NY8K",
      "expiresAt": -1,
      "ttl": -1,
      "description": "Sigfox callback authentication token",
      "fingerprint": "4ee98cb8c614e99213e7695f822e42325d86c93cfaf39cb40e860939e784c8e6",
      "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJfaWQiOiJNeSIsImlhdCI6MTU3MzE4NTkzNSwiZXhwIjoxNTczMTg1OTM0fQ.08qAnSD03V0N1OcviGVUAZEjjv4DxULTgoQQwojn1PA"
    }
  }
}