API keys
API keys
API keys are used to interact with our Video API.
You will need to create your first (perhaps only) API key using our dashboard (since you need to make an authenticated request to get an API key. So for the first one, you use your email/password to authenticate).
You can manage API keys by making the following requests:
| Request | Description |
|---|---|
| GET /keys | Return the details of all of the keys in your account |
| GET /keys/:id | Return the details of a single key |
| PATCH /keys/:id | Update a key |
| DELETE /keys/:id | Delete a key |
| POST /keys | Create a key |
GET /keys
Return the details of all of the keys in your account. API keys are not scoped to a particular user and so have their own, independent level of access.
Example request
curl \-H "Authorization: Bearer YOUR-API-KEY" \"https://api.vidbeo.com/v2/keys"Example response
{ "success": true, "result": [ { "id": "abcde12345abcde12345a", "name": "Example key", "type": "api", "permissions": [], "ips": [], "created_by": "abcde12345abcde12345a", "created_time": "2021-01-01T12:00:00.000Z", "updated_by": "abcde12345abcde12345a", "updated_time": "2021-01-01T12:00:00.000Z" }, ... ], "links": {}, "errors": []}Optional parameters
| Name | Type | Default | Information |
|---|---|---|---|
| limit | String | 25 | Maximum number to return |
| cursor | String | "" | Used to get the next page of results: if applicable we return this as part of the links.next URL |
GET /keys/:id
Return the details of a single key.
Example request
curl \-H "Authorization: Bearer YOUR-API-KEY" \"https://api.vidbeo.com/v2/keys/abcde12345abcde12345a"Example response
{ "success": true, "result": { "id": "abcde12345abcde12345a", "name": "Example key", "type": "api", "permissions": [], "ips": [], "created_by": "abcde12345abcde1234a", "created_time": "2021-02-01T00:00:00.000Z", "updated_by": "abcde12345abcde12345a", "updated_time": "2021-02-01T00:00:00.000Z" }, "links": null, "errors": []}Response format
| Key | Type | Description |
|---|---|---|
| id | String | The unique identifier given to this key |
| name | String | The name given to this key |
| type | String | The type of key |
| permissions | Array | What actions should this key be limited to. We currently support [] for read-write and ["fetch"] for read-only |
| ips | Array | If this key should only be accepted for API requests from particular IP addresses, those IPs, as strings |
| created_by | String | The ID of the user who created it (if known) |
| created_time | String | The date and time it was created |
| updated_by | String | The ID of the user who last modified it (if known) |
| updated_time | String | The date and time it was last modified |
PATCH /keys/:id
Update a key.
The body of the request should contain one, or more, attributes that you would like to update for the key. Please be very careful when making changes to existing items to avoid losing data, particularly if a particular key has sub-keys.
Example request
curl \-g \-H "Authorization: Bearer YOUR-API-KEY" \-H "Content-Type: application/json" \-X PATCH \-d '{"name":"New name"}' \"https://api.vidbeo.com/v2/keys/abcde12345abcde12345a"Example response
{ "success": true, "result": { "id": "abcde12345abcde12345a", "name": "New name", "type": "api", "permissions": [], "ips": [], "created_by": "abcde12345abcde1234a", "created_time": "2021-02-01T00:00:00.000Z", "updated_by": "abcde12345abcde12345a", "updated_time": "2021-02-01T00:00:00.000Z" }, "links": null, "errors": []}DELETE /keys/:id
Delete a key.
Example request
curl \-H "Authorization: Bearer YOUR-API-KEY" \-X DELETE \"https://api.vidbeo.com/v2/keys/abcde12345abcde12345a"Example response
{ "success": true, "result": {}, "links": null, "errors": []}POST /keys
Create a key.
Note the addition of the value field in the response. That is only revealed once here so make a note of it.
Example request
curl \-g \-H "Authorization: Bearer YOUR-API-KEY" \-H "Content-Type: application/json" \-X POST \-d '{"type":"api", "name": "Example", "permissions": [], "ips": ["1.2.3.4"]}' \"https://api.vidbeo.com/v2/keys"Example response
{ "success": true, "result": { "id": "abcde12345abcde12345a", "name": "Example", "type": "api", "permissions": [], "ips": ["1.2.3.4"], "value": "THE-NEW-API-KEY", "created_by": "abcde12345abcde1234a", "created_time": "2021-02-01T00:00:00.000Z", "updated_by": "abcde12345abcde12345a", "updated_time": "2021-02-01T00:00:00.000Z" }, "links": null, "errors": []}Required parameters
You need to provide a type (we currently only support "api"), a name, a value for permissions (we currently only support either [] for a read/write key, and ['fetch'] for limiting the key to read-only, and an array of ips to limit the IP(s) the key can be used from. An empty array (the default) means any IP and should be used unless you know all the IPs your servers use and that they won't change.
| Key | Type | Description |
|---|---|---|
| type | String | The type of key (we currently only support "api") |
| name | String | The name of the key (1-50 characters) |
| permissions | Array | The level of access this key grants. We currently support [] for read/write or ["fetch"] for read-only |
| ips | Array | If this key should only be allowed to be used from particular IP addresses, those IPs, as strings. Send an empty array for any |