RPC API V1

Driplimit works with a JSON RPC API. All calls are made via HTTP using the POST method. The API returns 200 OK or 204 CREATED on success.

See Errors section in case of failure.

Keys

`POST /v1/keys.create`

Create a key

Headers

Content-Type: application/json - tells the service you wish to communicate with json
Authorization: Bearer <token> - the service key token

Parameters

payload *driplimit.payload -
ksid string - The id of the keyspace to which the key belongs to (required)
expires_in integer - The duration in milliseconds after which the key expires
expires_at timestamp - The time at which the key expires (expires_at takes precedence over expires_in)
ratelimit object - The rate limit configuration for the key (required)
- limit integer - The rate limit
- refill_rate integer - The rate at which the rate limit refills
- refill_interval integer - The interval at which the rate limit refills

cURL example

$ curl -X POST \
       -H "Content-Type: application/json" \
       -H "Authorization: Bearer <token>" \
       --data '
        {
          "ksid": "ks_abc",
          "expires_in": 300000,
          "expires_at": "0001-01-01T00:00:00Z",
          "ratelimit": {
            "limit": 5,
            "refill_rate": 1,
            "refill_interval": 1000
          }
        }' https://demo.driplim.it/v1/keys.create

{
  "kid": "k_xyz",
  "ksid": "ks_abc",
  "token": "demo_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
  "created_at": "2024-12-12T04:49:53.41993172Z",
  "ratelimit": {
    "state": {
      "remaining": 5,
      "last_refilled": "2024-12-12T04:49:53.41993214Z"
    },
    "limit": 5,
    "refill_rate": 1,
    "refill_interval": 1000
  },
  "expires_at": "2024-12-12T04:54:53.41993186Z"
}

`POST /v1/keys.check`

Check a key

Headers

Content-Type: application/json - tells the service you wish to communicate with json
Authorization: Bearer <token> - the service key token

Parameters

payload *driplimit.payload -
ksid string - The id of the keyspace to which the key belongs to (required)
token string - The token to check (required)

cURL example

$ curl -X POST \
       -H "Content-Type: application/json" \
       -H "Authorization: Bearer <token>" \
       --data '
        {
          "ksid": "ks_abc",
          "token": "demo_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
        }' https://demo.driplim.it/v1/keys.check

{
  "kid": "k_xyz",
  "ksid": "ks_abc",
  "created_at": "2024-12-12T04:49:53.419934465Z",
  "ratelimit": {
    "state": {
      "remaining": 4,
      "last_refilled": "2024-12-12T04:49:53.419934615Z"
    },
    "limit": 5,
    "refill_rate": 1,
    "refill_interval": 1000
  },
  "expires_at": "2024-12-12T04:54:53.419934515Z"
}

`POST /v1/keys.list`

List keys

Headers

Content-Type: application/json - tells the service you wish to communicate with json
Authorization: Bearer <token> - the service key token

Parameters

payload *driplimit.payload -
list object - The list options
- page integer - The page number
- limit integer - The number of items per page
ksid string - The id of the keyspace to which the keys belong to (required)

cURL example

$ curl -X POST \
       -H "Content-Type: application/json" \
       -H "Authorization: Bearer <token>" \
       --data '
        {
          "list": {
            "page": 1,
            "limit": 10
          },
          "ksid": "ks_abc"
        }' https://demo.driplim.it/v1/keys.list

{
  "list": {
    "page": 1,
    "limit": 10,
    "last_page": 1
  },
  "keys": [
    {
      "kid": "k_xyz",
      "ksid": "ks_abc",
      "created_at": "2024-12-12T04:49:53.419935817Z",
      "ratelimit": {
        "state": {
          "remaining": 4,
          "last_refilled": "2024-12-12T04:49:53.419935947Z"
        },
        "limit": 5,
        "refill_rate": 1,
        "refill_interval": 1000
      },
      "expires_at": "2024-12-12T04:54:53.419935877Z"
    }
  ]
}

`POST /v1/keys.get`

Get a key

Headers

Content-Type: application/json - tells the service you wish to communicate with json
Authorization: Bearer <token> - the service key token

Parameters

payload *driplimit.payload -
ksid string - The id of the keyspace to which the key belongs to (required)
kid string - The id of the key to get (kid takes precedence over token if both are provided)
token string - The token of the key to get

cURL example

$ curl -X POST \
       -H "Content-Type: application/json" \
       -H "Authorization: Bearer <token>" \
       --data '
        {
          "ksid": "ks_abc",
          "kid": "k_xyz",
          "token": ""
        }' https://demo.driplim.it/v1/keys.get

{
  "kid": "k_xyz",
  "ksid": "ks_abc",
  "created_at": "2024-12-12T04:49:53.41993731Z",
  "ratelimit": {
    "state": {
      "remaining": 4,
      "last_refilled": "2024-12-12T04:49:53.41993744Z"
    },
    "limit": 5,
    "refill_rate": 1,
    "refill_interval": 1000
  },
  "expires_at": "2024-12-12T04:54:53.41993736Z"
}

`POST /v1/keys.delete`

Delete a key from a keyspace

Headers

Content-Type: application/json - tells the service you wish to communicate with json
Authorization: Bearer <token> - the service key token

Parameters

payload *driplimit.payload -
ksid string - The id of the keyspace to which the key belongs to (required)
kid string - The id of the key to delete (required)

cURL example

$ curl -X POST \
       -H "Content-Type: application/json" \
       -H "Authorization: Bearer <token>" \
       --data '
        {
          "ksid": "ks_abc",
          "kid": "k_xyz"
        }' https://demo.driplim.it/v1/keys.delete

null

Keyspaces

`POST /v1/keyspaces.get`

Get keyspace by ID

Headers

Content-Type: application/json - tells the service you wish to communicate with json
Authorization: Bearer <token> - the service key token

Parameters

payload *driplimit.payload -
ksid string - The id of the keyspace to get (required)

cURL example

$ curl -X POST \
       -H "Content-Type: application/json" \
       -H "Authorization: Bearer <token>" \
       --data '
        {
          "ksid": "ks_abc"
        }' https://demo.driplim.it/v1/keyspaces.get

{
  "ksid": "ks_abc",
  "name": "demo.yourapi.com (env: production)",
  "keys_prefix": "demo_",
  "ratelimit": {
    "limit": 100,
    "refill_rate": 1,
    "refill_interval": 1000
  }
}

`POST /v1/keyspaces.list`

Get keyspace by ID

Headers

Content-Type: application/json - tells the service you wish to communicate with json
Authorization: Bearer <token> - the service key token

Parameters

payload *driplimit.payload -
list object - The list options
- page integer - The page number
- limit integer - The number of items per page

cURL example

$ curl -X POST \
       -H "Content-Type: application/json" \
       -H "Authorization: Bearer <token>" \
       --data '
        {
          "list": {
            "page": 1,
            "limit": 10
          }
        }' https://demo.driplim.it/v1/keyspaces.list

{
  "list": {
    "page": 1,
    "limit": 10,
    "last_page": 1
  },
  "keyspaces": [
    {
      "ksid": "ks_abc",
      "name": "demo.yourapi.com (env: production)",
      "keys_prefix": "demo_",
      "ratelimit": {
        "limit": 100,
        "refill_rate": 1,
        "refill_interval": 1000
      }
    }
  ]
}

`POST /v1/keyspaces.create`

Create a new keyspace

Headers

Content-Type: application/json - tells the service you wish to communicate with json
Authorization: Bearer <token> - the service key token

Parameters

payload *driplimit.payload -
name string - The name of the keyspace (required)
keys_prefix string - The prefix for the keys in the keyspace (required)
ratelimit object - The default rate limit configuration for keys in the keyspace
- limit integer - The rate limit
- refill_rate integer - The rate at which the rate limit refills
- refill_interval integer - The interval at which the rate limit refills

cURL example

$ curl -X POST \
       -H "Content-Type: application/json" \
       -H "Authorization: Bearer <token>" \
       --data '
        {
          "name": "demo.yourapi.com (env: production)",
          "keys_prefix": "demo_",
          "ratelimit": {
            "limit": 100,
            "refill_rate": 1,
            "refill_interval": 1000
          }
        }' https://demo.driplim.it/v1/keyspaces.create

{
  "ksid": "ks_abc",
  "name": "demo.yourapi.com (env: production)",
  "keys_prefix": "demo_",
  "ratelimit": {
    "limit": 100,
    "refill_rate": 1,
    "refill_interval": 1000
  }
}

`POST /v1/keyspaces.delete`

Delete a keyspace

Headers

Content-Type: application/json - tells the service you wish to communicate with json
Authorization: Bearer <token> - the service key token

Parameters

payload *driplimit.payload -
ksid string - The id of the keyspace to delete (required)

cURL example

$ curl -X POST \
       -H "Content-Type: application/json" \
       -H "Authorization: Bearer <token>" \
       --data '
        {
          "ksid": "ks_abc"
        }' https://demo.driplim.it/v1/keyspaces.delete

null

ServiceKeys

`POST /v1/serviceKeys.current`

Get the current authenticated service key

Headers

Content-Type: application/json - tells the service you wish to communicate with json
Authorization: Bearer <token> - the service key token

Parameters

cURL example

$ curl -X POST \
       -H "Content-Type: application/json" \
       -H "Authorization: Bearer <token>" \ https://demo.driplim.it/v1/serviceKeys.current

{
  "skid": "sk_uvw",
  "description": "cli generated admin service key at 2024-12-12T04:49:53Z",
  "admin": true,
  "keyspaces_policies": {
    "ks_abc": {
      "read": true,
      "write": true
    }
  },
  "created_at": "2024-12-12T04:49:53.419986081Z"
}

`POST /v1/serviceKeys.get`

Get the service key by ID or by token

Headers

Content-Type: application/json - tells the service you wish to communicate with json
Authorization: Bearer <token> - the service key token

Parameters

payload *driplimit.payload -
skid string - The id of the service key to get (skid takes precedence over token)
token string - The token of the service key to get

cURL example

$ curl -X POST \
       -H "Content-Type: application/json" \
       -H "Authorization: Bearer <token>" \
       --data '
        {
          "skid": "sk_uvw",
          "token": ""
        }' https://demo.driplim.it/v1/serviceKeys.get

{
  "skid": "sk_uvw",
  "description": "cli generated admin service key at 2024-12-12T04:49:53Z",
  "admin": true,
  "keyspaces_policies": {
    "ks_abc": {
      "read": true,
      "write": true
    }
  },
  "created_at": "2024-12-12T04:49:53.419990038Z"
}

`POST /v1/serviceKeys.list`

List all service keys

Headers

Content-Type: application/json - tells the service you wish to communicate with json
Authorization: Bearer <token> - the service key token

Parameters

payload *driplimit.payload -
list object - The list options
- page integer - The page number
- limit integer - The number of items per page

cURL example

$ curl -X POST \
       -H "Content-Type: application/json" \
       -H "Authorization: Bearer <token>" \
       --data '
        {
          "list": {
            "page": 1,
            "limit": 10
          }
        }' https://demo.driplim.it/v1/serviceKeys.list

{
  "list": {
    "page": 1,
    "limit": 10,
    "last_page": 1
  },
  "service_keys": [
    {
      "skid": "sk_uvw",
      "description": "cli generated admin service key at 2024-12-12T04:49:53Z",
      "admin": true,
      "keyspaces_policies": {
        "ks_abc": {
          "read": true,
          "write": true
        }
      },
      "created_at": "2024-12-12T04:49:53.419992402Z"
    }
  ]
}

`POST /v1/serviceKeys.delete`

Delete a service key

Headers

Content-Type: application/json - tells the service you wish to communicate with json
Authorization: Bearer <token> - the service key token

Parameters

payload *driplimit.payload -
skid string - The id of the service key to delete (required)

cURL example

$ curl -X POST \
       -H "Content-Type: application/json" \
       -H "Authorization: Bearer <token>" \
       --data '
        {
          "skid": "sk_uvw"
        }' https://demo.driplim.it/v1/serviceKeys.delete

null

`POST /v1/serviceKeys.create`

Get the service key by ID or by token

Headers

Content-Type: application/json - tells the service you wish to communicate with json
Authorization: Bearer <token> - the service key token

Parameters

payload *driplimit.payload -
skid string - the id of the service key. Automatically generated if empty
description string - The description of the service key
admin bool - The admin flag of the service key
keyspaces_policies map - The keyspaces policies of the service key. Map keys are the keyspace ids and the values are the policies for the keyspace
- string - keys of the map (required)
  - read bool - Read permission
  - write bool - Write permission

cURL example

$ curl -X POST \
       -H "Content-Type: application/json" \
       -H "Authorization: Bearer <token>" \
       --data '
        {
          "skid": "",
          "description": "api generated non admin service key",
          "admin": false,
          "keyspaces_policies": {
            "ks_abc": {
              "read": true,
              "write": false
            }
          }
        }' https://demo.driplim.it/v1/serviceKeys.create

{
  "skid": "sk_uvw",
  "description": "api generated non admin service key",
  "admin": true,
  "keyspaces_policies": {
    "ks_abc": {
      "read": true,
      "write": false
    }
  },
  "created_at": "2024-12-12T04:49:53.419994587Z"
}

`POST /v1/serviceKeys.set_token`

Set a new token for a service key

Headers

Content-Type: application/json - tells the service you wish to communicate with json
Authorization: Bearer <token> - the service key token

Parameters

payload *driplimit.payload -
skid string - the id of the service key. Automatically generated if empty (required)
token string - the new service key token (required)

cURL example

$ curl -X POST \
       -H "Content-Type: application/json" \
       -H "Authorization: Bearer <token>" \
       --data '
        {
          "skid": "ks_abc",
          "token": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
        }' https://demo.driplim.it/v1/serviceKeys.set_token

null

Errors

If HTTP response code is greater than or equal to 400, the api returns a json object indicating the reason of the failure:

{
  "error": "the reason of the failure",
  "invalid_fields": [
    "field1",
    "field2"
  ]
}

invalid_fields can also be integrated in the error response if one or more input parameters are invalids.

HTTP response code

200 ok
204 created
400 invalid payload
401 unauthorized
403 cannot delete itself
404 not found
409 already exists
419 key expired
422 unprocessable entity
429 rate limit exceeded

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

RPC API V1

Keys

`POST /v1/keys.create`

`POST /v1/keys.check`

`POST /v1/keys.list`

`POST /v1/keys.get`

`POST /v1/keys.delete`

Keyspaces

`POST /v1/keyspaces.get`

`POST /v1/keyspaces.list`

`POST /v1/keyspaces.create`

`POST /v1/keyspaces.delete`

ServiceKeys

`POST /v1/serviceKeys.current`

`POST /v1/serviceKeys.get`

`POST /v1/serviceKeys.list`

`POST /v1/serviceKeys.delete`

`POST /v1/serviceKeys.create`

`POST /v1/serviceKeys.set_token`

Errors

HTTP response code

Clone this wiki locally