SFTPGo Octri Preview
POST/apikeys

Create an API key

Creates a new API key for an administrator or user scope. Set scope to 1 for administrator scope or 2 for user scope, and use admin or user to associate the key with a specific account. A 201 response returns the generated key, so store it securely.

  • IdempotentThe SDK sends Idempotency-Key, so a retried request is only applied once.

11 body fields

API key details. No body fields are marked as required by the schema.

adminstringoptional
admin associated with this API key. If empty and the scope is "admin scope" the key can impersonate any admin
created_atintegeroptional
creation time as unix timestamp in milliseconds
descriptionstringoptional
optional description
expires_atintegeroptional
expiration time as unix timestamp in milliseconds. Once set, the expiration date cannot be extended. It can only be shortened.
idstringoptional
unique key identifier
keystringoptional
We store the hash of the key. This is just like a password. For security reasons this field is omitted when you search/get API keys
last_use_atintegeroptional
last use time as unix timestamp in milliseconds. It is saved at most once every 10 minutes
namestringoptional
User friendly key name
scopeintegeroptional
Options: * `1` - admin scope. The API key will be used to impersonate an SFTPGo admin * `2` - user scope. The API key will be used to impersonate an SFTPGo user
Allowed:12
updated_atintegeroptional
last update time as unix timestamp in milliseconds
userstringoptional
username associated with this API key. If empty and the scope is "user scope" the key can impersonate any user

6 status codes
201Returns an object containing the generated API key and a message.
keystringoptional
generated API key
mesagestringoptional
400Returned when the request is invalid.
errorstringoptional
error description if any
messagestringoptional
message, can be empty
401Returned when the request is unauthenticated.
errorstringoptional
error description if any
messagestringoptional
message, can be empty
403Returned when the authenticated user is not permitted to create an API key.
errorstringoptional
error description if any
messagestringoptional
message, can be empty
500Returned when an internal server error occurs.
errorstringoptional
error description if any
messagestringoptional
message, can be empty
defaultUnexpected Error
errorstringoptional
error description if any
messagestringoptional
message, can be empty

Error handling

A 400 is returned when the request is invalid, a 401 when the authenticated user does not present valid credentials, and a 403 when the authenticated user lacks permission to create API keys. scope must be 1 or 2; a 500 indicates an internal server error.