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:

RequestDescription
GET /keysReturn the details of all of the keys in your account
GET /keys/:idReturn the details of a single key
PATCH /keys/:idUpdate a key
DELETE /keys/:idDelete a key
POST /keysCreate 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

NameTypeDefaultInformation
limitString25Maximum number to return
cursorString""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

KeyTypeDescription
idStringThe unique identifier given to this key
nameStringThe name given to this key
typeStringThe type of key
permissionsArrayWhat actions should this key be limited to. We currently support [] for read-write and ["fetch"] for read-only
ipsArrayIf this key should only be accepted for API requests from particular IP addresses, those IPs, as strings
created_byStringThe ID of the user who created it (if known)
created_timeStringThe date and time it was created
updated_byStringThe ID of the user who last modified it (if known)
updated_timeStringThe 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.

KeyTypeDescription
typeStringThe type of key (we currently only support "api")
nameStringThe name of the key (1-50 characters)
permissionsArrayThe level of access this key grants. We currently support [] for read/write or ["fetch"] for read-only
ipsArrayIf this key should only be allowed to be used from particular IP addresses, those IPs, as strings. Send an empty array for any