Creating a token¶
Check out the Permissions list for a complete list of permissions.
| Parameters | |
|---|---|
| name | description |
| roles | A list of roles allowed for user. See permissions/configuration reference page |
| data.tags | List of allowed tags to use in upload endpoints (OPTIONAL) |
| data.allowedMimeTypes | List of allowed mime types (OPTIONAL) |
| data.maxAllowedFileSize | Number of bytes of maximum file size (OPTIONAL) |
| data.allowedUserAgents | List of allowed User-Agent header values (ex. to restrict token to single browser) (OPTIONAL) |
| data.allowedIpAddresses | List of allowed IP addresses (ex. to restrict one-time-token to single person/session) (OPTIONAL) |
| data.secureCopyEncryptionMethod | Encryption method in SecureCopy mechanism (if using) (OPTIONAL) |
| data.secureCopyEncryptionKey | Encryption key in SecureCopy component. If active, then client using this token will be downloading encrypted files (zero-knowledge) (OPTIONAL) |
| expires | Expiration date, or “auto”, “automatic”, “never”. Empty value means same as “auto” |
| id | Custom UUIDv4 (requires: security.create_predictable_token_ids role or to be an admin) |
POST /auth/token/generate?_token=your-admin-token-there
{
"roles": ["collections.create_new", "collections.manage_tokens_in_allowed_collections"],
"data": {
"tags": [],
"allowedMimeTypes": ["image/jpeg", "image/png", "image/gif"],
"maxAllowedFileSize": 14579,
"allowedUserAgents": ["Mozilla/5.0 (X11; Linux x86_64; rv:57.0) Gecko/20100101 Firefox/57.0"],
"allowedIpAddresses": ["192.168.1.10"]
},
"expires": "2020-05-05 08:00:00"
}
Example response:
{
"status": true,
"error_code": null,
"http_code": 200,
"errors": [],
"context": [],
"message": "Token created",
"token": {
"id": "ca6a2635-d2cb-4682-ba81-3879dd0e8a77",
"active": true,
"expires": "2020-05-05 08:00:00",
"expired": false,
"data": {
"tags": [],
"allowedMimeTypes": ["image/jpeg", "image/png", "image/gif"],
"maxAllowedFileSize": 14579,
"allowedIpAddresses": ["192.168.1.10"],
"allowedUserAgents": ["Mozilla/5.0 (X11; Linux x86_64; rv:57.0) Gecko/20100101 Firefox/57.0"],
"secureCopyEncryptionKey": "",
"secureCopyEncryptionMethod": ""
},
"roles": [
"collections.create_new",
"collections.add_tokens_to_allowed_collections"
]
}
}
Required roles:
- security.generate_tokens
Searching tokens¶
Finds tokens matching search criteria.
GET /auth/search?_token=your-token-there&q=&limit=50&page=1
Example response:
{
"status": true,
"error_code": null,
"http_code": 200,
"errors": [],
"context": {
"pagination": {
"page": 1,
"perPageLimit": 5,
"maxPages": 7
}
},
"message": "Matches found",
"data": [
{
"id": "1c2c84f2-d488-4ea0-9c88-d25aab139ac4",
"active": true,
"data": {
"tags": [],
"allowedMimeTypes": [],
"maxAllowedFileSize": null,
"allowedIpAddresses": [],
"allowedUserAgents": [],
"secureCopyEncryptionKey": "",
"secureCopyEncryptionMethod": ""
},
"roles": [
"upload.images"
]
},
{
"id": "669d4918-b156-412d-9c89-ba01d6eef9d4",
"active": true,
"data": {
"tags": [],
"allowedMimeTypes": [],
"maxAllowedFileSize": null,
"allowedIpAddresses": [],
"allowedUserAgents": [],
"secureCopyEncryptionKey": "",
"secureCopyEncryptionMethod": ""
},
"roles": [
"security.generate_tokens"
]
},
{
"id": "fad05629-51f6-4ddf-b21a-315a1451670d",
"active": true,
"data": {
"tags": [],
"allowedMimeTypes": [],
"maxAllowedFileSize": null,
"allowedIpAddresses": [],
"allowedUserAgents": [],
"secureCopyEncryptionKey": "",
"secureCopyEncryptionMethod": ""
},
"roles": [
"upload.images"
]
},
{
"id": "3235ad82-666f-4963-a751-b4dff3168c4c",
"active": true,
"expires": "2020-05-05 08:00:00",
"expired": false,
"data": {
"tags": [
"user_uploads.u123",
"user_uploads"
],
"allowedMimeTypes": [
"image\/jpeg",
"image\/png",
"image\/gif"
],
"maxAllowedFileSize": 100,
"allowedIpAddresses": [],
"allowedUserAgents": [],
"secureCopyEncryptionKey": "",
"secureCopyEncryptionMethod": ""
},
"roles": [
"upload.images"
]
},
{
"id": "dafe83fa-7813-4d84-a625-16c6657fec9f",
"active": true,
"data": {
"tags": [],
"allowedMimeTypes": [],
"maxAllowedFileSize": null,
"allowedIpAddresses": [],
"allowedUserAgents": [],
"secureCopyEncryptionKey": "",
"secureCopyEncryptionMethod": ""
},
"roles": [
"collections.create_new",
"collections.manage_tokens_in_allowed_collections"
]
}
]
}
Required roles:
- security.search_for_tokens
- security.authentication_lookup
Looking up a token¶
GET /auth/token/D0D12FFF-DD04-4514-8E5D-D51542DEBCFA?_token=your-admin-token-there
Example response:
{
"status": true,
"error_code": null,
"http_code": 200,
"errors": [],
"context": [],
"message": "Token found",
"token": {
"id": "ca6a2635-d2cb-4682-ba81-3879dd0e8a77",
"active": true,
"data": {
"tags": [],
"allowedMimeTypes": [],
"maxAllowedFileSize": 0,
"allowedIpAddresses": [],
"allowedUserAgents": [],
"secureCopyEncryptionKey": "",
"secureCopyEncryptionMethod": ""
},
"roles": [
"security.administrator",
"upload.images",
"upload.documents",
"upload.backup",
"upload.all",
"security.authentication_lookup",
"security.search_for_tokens",
"security.overwrite",
"security.generate_tokens",
"security.use_technical_endpoints",
"deletion.all_files_including_protected_and_unprotected",
"view.any_file",
"view.files_from_all_tags",
"view.can_use_listing_endpoint_at_all",
"security.revoke_tokens",
"collections.create_new",
"collections.create_new.with_custom_id",
"collections.allow_infinite_limits",
"collections.delete_allowed_collections",
"collections.modify_any_collection_regardless_if_token_was_allowed_by_collection",
"collections.modify_details_of_allowed_collections",
"collections.view_all_collections",
"collections.can_use_listing_endpoint",
"collections.manage_tokens_in_allowed_collections",
"collections.upload_to_allowed_collections",
"collections.list_versions_for_allowed_collections",
"collections.delete_versions_for_allowed_collections",
"securecopy.stream",
"securecopy.all_secrets_read"
]
}
}
Required roles:
- security.authentication_lookup
Revoking a token¶
DELETE /auth/token/D0D12FFF-DD04-4514-8E5D-D51542DEBCFA?_token=your-admin-token-there
Example response:
{
"status": true,
"error_code": null,
"http_code": 201,
"errors": [],
"context": [],
"message": "Token was deleted",
"token": {
"id": null,
"active": true,
"expires": "2020-05-05 08:00:00",
"expired": false,
"data": {
"tags": [],
"allowedMimeTypes": [],
"maxAllowedFileSize": 0,
"allowedIpAddresses": [],
"allowedUserAgents": [],
"secureCopyEncryptionKey": "",
"secureCopyEncryptionMethod": ""
},
"roles": [
"security.administrator",
"upload.images",
"upload.documents",
"upload.backup",
"upload.all",
"security.authentication_lookup",
"security.search_for_tokens",
"security.overwrite",
"security.generate_tokens",
"security.use_technical_endpoints",
"deletion.all_files_including_protected_and_unprotected",
"view.any_file",
"view.files_from_all_tags",
"view.can_use_listing_endpoint_at_all",
"security.revoke_tokens",
"collections.create_new",
"collections.create_new.with_custom_id",
"collections.allow_infinite_limits",
"collections.delete_allowed_collections",
"collections.modify_any_collection_regardless_if_token_was_allowed_by_collection",
"collections.modify_details_of_allowed_collections",
"collections.view_all_collections",
"collections.can_use_listing_endpoint",
"collections.manage_tokens_in_allowed_collections",
"collections.upload_to_allowed_collections",
"collections.list_versions_for_allowed_collections",
"collections.delete_versions_for_allowed_collections",
"securecopy.stream",
"securecopy.all_secrets_read"
]
}
}
Required roles:
- security.revoke_tokens