Download OpenAPI specification:Download
Documentation of the Open-Xchange OX Guard HTTP API
The login module is used to obtain a Guard authentication token which can be used to decrypt encrypted data without providing the user's password.
Performs a login against the OX Guard Server in order to obtain an authentication token and various user specific settings.
See also auth-token for creating and attaching an authentication token to the user's session.
session required | string A session ID previously obtained from the Appsuite HTTP login module. |
The new password which will be set to protect the private key.
encr_password | string The plain text password of the user's OX Guard key, or null if just fetching user settings. |
language | string Default: "en_EN" The language code of the client (for example "de_DE"), or null for the default value (en_EN). |
Returns an object containing authentication information and settings.
{- "encr_password": "string",
- "language": "en_EN"
}
{- "server": "string",
- "cid": 0,
- "primaryEmail": "string",
- "pubKey": "string",
- "auth": "string",
- "recoveryAvail": true,
- "lang": {
- "property1": "string",
- "property2": "string"
}, - "settings": {
- "pgpdefault": true,
- "pgpsign": true,
- "inline": true,
- "noDeletePrivate": true,
- "noRecovery": true,
- "noDeleteRecovery": true,
- "min_password_length": 0,
- "password_length": 0
}
}
Destroys any Guard sessions for the user.
session required | string A session ID previously obtained from the Appsuite HTTP login module. |
Returns OK if successful, otherwise error JSON
Performs a guest login against the OX Guard Server in order to obtain an authentication token and/or various user specific settings.
Data containing guest credentials.
username required | string The guest's username |
password | string The guest password. This parameter can be omitted if the guest logs in the first time AND an initial password is not set/required. |
guest login response
{- "username": "string",
- "password": "string"
}
{- "productName": "string",
- "auth": "string",
- "recoveryAvail": true,
- "settings": {
- "min_password_length": 0
}
}
Changes the password of the user's current key
session required | string A session ID previously obtained from the Appsuite HTTP login module. |
Data containing necessary information in order to change the user's password.
oldpass required | string The current password of the key which will be replaced. |
newpass required | string The new password to set. |
Returns an object containing new authentication information.
{- "oldpass": "string",
- "newpass": "string"
}
{- "auth": "string"
}
Gets the user's secondary email address where password reset information will be sent to.
session required | string A session ID previously obtained from the Appsuite HTTP login module. |
Returns the user's secondary email address or an empty response if no secondary email address is set for the user.
Sets the user's secondary email address where password reset information will be sent to.
session required | string A session ID previously obtained from the Appsuite HTTP login module. |
Data containing necessary information in order to change the user's password.
password required | string The password of the user's current OX Guard key. |
email required | string The new secondary email address to set. |
"OK" or an error message in case of an error.
{- "password": "string",
- "email": "string"
}
Resets the password of the user's current key to a new random password which will be sent to the user's secondary email address, or primary address if no secondary email address is available.
session required | string A session ID previously obtained from the Appsuite HTTP login module. |
"ok" if the new password was sent to the secondary email address, "primary" if it was sent to the primary email address, or an error message if password reset request failed.
Checks if the user has at least one public and/or private PGP key available.
session required | string A session ID previously obtained from the Appsuite HTTP login module. |
A JSON object which contains if the user has a private and/or public key setup.
{- "data": {
- "hasPrivateKey": true,
- "hasPublicKey": true
}, - "error": "string",
- "error_params": [
- "string"
], - "error_id": "string",
- "error_desc": "string",
- "error_stack": [
- "string"
], - "code": "string",
- "categories": "string",
- "category": 0
}
Creates a new PGP key ring for the user and marks the new key ring as "current".
session required | string A session ID previously obtained from the Appsuite HTTP login module. |
password required | string The new password which will be set to protect the private key. Can be omitted if e_password is used. |
e_password | string The new, RSA encrypted, password which will be set to protect the private key. |
name required | string The user's name which will be part of the key identity. |
string Optional second email address to be used for password resets |
The new created key ring.
{- "data": {
- "userId": 0,
- "contextId": 0,
- "current": true,
- "passwordModificationTimestamp": 0,
- "publicRing": {
- "ring": "string",
- "hash": "string",
- "keys": [
- {
- "id": 0,
- "expired": true,
- "hasPrivateKey": true,
- "fingerPrint": "string",
- "userIds": [
- "string"
], - "encryptionKey": true,
- "masterKey": true,
- "validSeconds": 0,
- "revoked": true,
- "creationTime": 0
}
]
}, - "privateRing": {
- "ring": "string",
- "keys": [
- {
- "id": 0,
- "masterKey": true,
- "expired": true,
- "userIds": [
- "string"
]
}
]
}
}, - "error": "string",
- "error_params": [
- "string"
], - "error_id": "string",
- "error_desc": "string",
- "error_stack": [
- "string"
], - "code": "string",
- "categories": "string",
- "category": 0
}
Deletes a specific PGP key ring
session required | string A session ID previously obtained from the Appsuite HTTP login module. |
keyid required | string The master key ID of the key ring which should be deleted. |
password required | string The password of the private key. Can be omitted if e_password is used or if public key only |
e_password | string The, RSA encrypted, password of the private key. |
An empty JSON response in case the key has been deleted.
Gets the collection of public PGP key rings associated with a contact.
session required | string A session ID previously obtained from the Appsuite HTTP login module. |
contactFolder required | string Specifies the Folder of the contact |
contactID required | string Specifies the ID of the contact |
A collection of the public key rings associated with a contact.
{- "data": {
- "externalPublicKeyRings": [
- {
- "ids": "string",
- "shareLevel": 0,
- "inline": true,
- "owned": true,
- "shared": true,
- "guardKey": true,
- "publicRing": {
- "ring": "string",
- "hash": "string",
- "keys": [
- {
- "id": 0,
- "expired": true,
- "hasPrivateKey": true,
- "fingerPrint": "string",
- "userIds": [
- "string"
], - "encryptionKey": true,
- "masterKey": true,
- "validSeconds": 0,
- "revoked": true,
- "creationTime": 0
}
]
}
}
]
}, - "error": "string",
- "error_params": [
- "string"
], - "error_id": "string",
- "error_desc": "string",
- "error_stack": [
- "string"
], - "code": "string",
- "categories": "string",
- "category": 0
}
Gets the the user's collection of public PGP key rings.
session required | string A session ID previously obtained from the Appsuite HTTP login module. |
A collection of the user's public key rings.
{- "data": {
- "keyRings": [
- {
- "userId": 0,
- "contextId": 0,
- "current": true,
- "passwordModificationTimestamp": 0,
- "publicRing": {
- "ring": "string",
- "hash": "string",
- "keys": [
- {
- "id": 0,
- "expired": true,
- "hasPrivateKey": true,
- "fingerPrint": "string",
- "userIds": [
- "string"
], - "encryptionKey": true,
- "masterKey": true,
- "validSeconds": 0,
- "revoked": true,
- "creationTime": 0
}
]
}, - "privateRing": {
- "ring": "string",
- "keys": [
- {
- "id": 0,
- "masterKey": true,
- "expired": true,
- "userIds": [
- "string"
]
}
]
}
}
]
}, - "error": "string",
- "error_params": [
- "string"
], - "error_id": "string",
- "error_desc": "string",
- "error_stack": [
- "string"
], - "code": "string",
- "categories": "string",
- "category": 0
}
Gets a specific PGP key ring owned by the user containing public and/or private PGP keys. This request fetches detailed information about a specific PGP key ring.
session required | string A session ID previously obtained from the Appsuite HTTP login module. |
keyid | integer <int64> Specifies the ID of the key to fetch. If this parameter is missing the key marked as "current" is returned instead. |
keyType | string Default: "public_private" Enum: "public" "private" "public_private" Specifies if the public and/or the private key of the key ring should be fetched. |
password required | string The password of the private key (if keyType is set to 'private' or 'public_private'). Can be omitted if e_password is used. |
e_password | string The, RSA encrypted, password of the private key (if keyType is set to 'private' or 'public_private') |
The public and/or private part of the specified key ring.
{- "data": {
- "userId": 0,
- "contextId": 0,
- "current": true,
- "passwordModificationTimestamp": 0,
- "publicRing": {
- "ring": "string",
- "hash": "string",
- "keys": [
- {
- "id": 0,
- "expired": true,
- "hasPrivateKey": true,
- "fingerPrint": "string",
- "userIds": [
- "string"
], - "encryptionKey": true,
- "masterKey": true,
- "validSeconds": 0,
- "revoked": true,
- "creationTime": 0
}
]
}, - "privateRing": {
- "ring": "string",
- "keys": [
- {
- "id": 0,
- "masterKey": true,
- "expired": true,
- "userIds": [
- "string"
]
}
]
}
}, - "error": "string",
- "error_params": [
- "string"
], - "error_id": "string",
- "error_desc": "string",
- "error_stack": [
- "string"
], - "code": "string",
- "categories": "string",
- "category": 0
}
Downloads the ASCII armored representation of a specific PGP key ring owned by the user containing public and/or private PGP keys. This request fetches the raw ASCII armored PGP key ring data.
session required | string A session ID previously obtained from the Appsuite HTTP login module. |
keyid | integer <int64> Specifies the ID of the key to fetch. If this parameter is omitted the key marked as "current" is returned instead. |
keyType | string Default: "public_private" Enum: "public" "private" "public_private" Specifies if the public and/or the private key of the key ring should be fetched. |
password required | string The password of the private key (if keyType is set to 'private' or 'public_private'). Can be omitted if e_password is used. |
e_password | string The, RSA encrypted, password of the private key (if keyType is set to 'private' or 'public_private') |
The public and/or private part of the specified key ring as raw ASCII armored data.
Marks a Guard PGP key ring as "current".
session required | string A session ID previously obtained from the Appsuite HTTP login module. |
keyid required | integer <int64> The master key ID of the key ring which should be marked as "current". |
An empty response in case the key was successfully marked as current.
Uploads a new ASCII armored key ring to OX Guard. The key ring can contain public and/or private keys.
session required | string A session ID previously obtained from the Appsuite HTTP login module. |
key required | string <binary> The ASCII armored data of the key ring. |
keyPassword | string The password of the private key. Can be omitted if the uploaded key ring does only contain public keys. |
newPassword | string The new password to set for the imported private keys. Can be omitted if the uploaded key ring does only contain public keys. |
A collection of uploaded key rings.
{- "data": {
- "keyRings": [
- {
- "userId": 0,
- "contextId": 0,
- "current": true,
- "passwordModificationTimestamp": 0,
- "publicRing": {
- "ring": "string",
- "hash": "string",
- "keys": [
- {
- "id": 0,
- "expired": true,
- "hasPrivateKey": true,
- "fingerPrint": "string",
- "userIds": [
- "string"
], - "encryptionKey": true,
- "masterKey": true,
- "validSeconds": 0,
- "revoked": true,
- "creationTime": 0
}
]
}, - "privateRing": {
- "ring": "string",
- "keys": [
- {
- "id": 0,
- "masterKey": true,
- "expired": true,
- "userIds": [
- "string"
]
}
]
}
}
]
}, - "error": "string",
- "error_params": [
- "string"
], - "error_id": "string",
- "error_desc": "string",
- "error_stack": [
- "string"
], - "code": "string",
- "categories": "string",
- "category": 0
}
A user can upload public keys for other external communication partners. This requests uploads an ASCII armored public key of an external recipient for later user.
session required | string A session ID previously obtained from the Appsuite HTTP login module. |
key required | string <binary> The ASCII armored data of the key ring. |
A collection of imported external key rings.
{- "data": {
- "externalPublicKeyRings": [
- {
- "ids": "string",
- "shareLevel": 0,
- "inline": true,
- "owned": true,
- "shared": true,
- "guardKey": true,
- "publicRing": {
- "ring": "string",
- "hash": "string",
- "keys": [
- {
- "id": 0,
- "expired": true,
- "hasPrivateKey": true,
- "fingerPrint": "string",
- "userIds": [
- "string"
], - "encryptionKey": true,
- "masterKey": true,
- "validSeconds": 0,
- "revoked": true,
- "creationTime": 0
}
]
}
}
]
}, - "error": "string",
- "error_params": [
- "string"
], - "error_id": "string",
- "error_desc": "string",
- "error_stack": [
- "string"
], - "code": "string",
- "categories": "string",
- "category": 0
}
Gets a list of upload public keys for external recipients. A user can upload public key rings for other external communication partners. This requests gets the uploaded public key rings for externals including useful meta information.
session required | string A session ID previously obtained from the Appsuite HTTP login module. |
keyType | string Type of key to retrieve. Defaults to uploaded Public Keys. Other example is "autocrypt" |
The collection of uploaded external key rings.
{- "data": {
- "externalPublicKeyRings": [
- {
- "ids": "string",
- "shareLevel": 0,
- "inline": true,
- "owned": true,
- "shared": true,
- "guardKey": true,
- "publicRing": {
- "ring": "string",
- "hash": "string",
- "keys": [
- {
- "id": 0,
- "expired": true,
- "hasPrivateKey": true,
- "fingerPrint": "string",
- "userIds": [
- "string"
], - "encryptionKey": true,
- "masterKey": true,
- "validSeconds": 0,
- "revoked": true,
- "creationTime": 0
}
]
}
}
]
}, - "error": "string",
- "error_params": [
- "string"
], - "error_id": "string",
- "error_desc": "string",
- "error_stack": [
- "string"
], - "code": "string",
- "categories": "string",
- "category": 0
}
Marks an uploaded external recipient key as "inline". An external public key which is marked as "inline" produces PGP/INLNE email encryption by default.
session required | string A session ID previously obtained from the Appsuite HTTP login module. |
keyids required | string The ids parameter from the ExternalPublicKeyRing object as obtained from the GetExternalPublicKeys request. |
inline required | boolean True, to mark the key ring as "inline", False to mark it as "not inline". |
An empty response in case the key was marked as inline.
Deletes an uploaded external recipient key.
session required | string A session ID previously obtained from the Appsuite HTTP login module. |
keyids required | string The ids parameter from the ExternalPublicKeyRing object as obtained from the GetExternalPublicKeys request. |
keyType | string Type of key to retrieve. Defaults to uploaded Public Keys. Other example is "autocrypt" |
An empty response in case the key was deleted.
Adds a new user ID "name
session required | string A session ID previously obtained from the Appsuite HTTP login module. |
keyid required | integer <int64> The master key ID of the key ring which should be changed. |
name required | string The name part of "name |
email required | string The email part of "name |
An empty response in case the key was successfully marked as current.
Reovkes a PGP key ring.
session required | string A session ID previously obtained from the Appsuite HTTP login module. |
keyid required | integer <int64> Specifies the ID of the master-, or sub-key to revoke. |
password required | string The password of the private key. Can be omitted if e_password is used. |
e_password | string The, RSA encrypted, password of the private key. |
reason | string Default: "no_reason" Enum: "no_reason" "key_superseded" "key_compromised" "key_retired" "user_no_longer_valid" Specifies the reason why the key is being revoked. |
An empty response in case the key was revoked.
Queries the public key of a recipient.
session required | string A session ID previously obtained from the Appsuite HTTP login module. |
string The email address of the recipient to search a key for. | |
keyid | integer <int64> Instead of using the email parameter it is also possible to perform the search by key ID. |
create | boolean True to create non existing keys for the requested user, False to not create keys with this request (default). |
The public key ring of the recipient and some additional meta data.
{- "data": {
- "publicRing": {
- "ring": "string",
- "hash": "string",
- "keys": [
- {
- "id": 0,
- "expired": true,
- "hasPrivateKey": true,
- "fingerPrint": "string",
- "userIds": [
- "string"
], - "encryptionKey": true,
- "masterKey": true,
- "validSeconds": 0,
- "revoked": true,
- "creationTime": 0
}
]
}, - "guest": true,
- "newKey": true,
- "newCreated": true,
- "keySource": {
- "name": "string",
- "trustLevel": 0,
- "trusted": true
}
}, - "error": "string",
- "error_params": [
- "string"
], - "error_id": "string",
- "error_desc": "string",
- "error_stack": [
- "string"
], - "code": "string",
- "categories": "string",
- "category": 0
}
Gets the signatures for a user's key.
session required | string A session ID previously obtained from the Appsuite HTTP login module. |
keyid required | integer <int64> The ID of the key to get a list of signatures for. |
subkeys | boolean Default: false True to include signatures for subkeys (only if the given keyid belongs to a master key). False to just return the signatures for the given key. |
The public key ring of the recipient and some additional meta data.
{- "data": {
- "signatures": [
- {
- "signatureType": 0,
- "description": "string",
- "userId": "string",
- "keyId": "string",
- "fingerPrint": "string",
- "issuer": "string",
- "issuerKeyId": "string",
- "issuerFingerPrint": "string",
- "verified": true,
- "keyMissing": true,
- "hashAlgorithm": 0,
- "creationTime": 0,
- "version": 0
}
]
}, - "error": "string",
- "error_params": [
- "string"
], - "error_id": "string",
- "error_desc": "string",
- "error_stack": [
- "string"
], - "code": "string",
- "categories": "string",
- "category": 0
}
Send the autocrpt header to Guard to import or return key details. Client should verify the address in header is part of the mime email
session required | string A session ID previously obtained from the Appsuite HTTP login module. |
add | boolean If the key should be automatically imported. If false, only key information is returned |
confirmed | boolean True if the user has confirmed this key and wants it added. Marks the key as verified |
header required | string The value of the autoCrypt header from the MIME email |
sent_date required | string The sent date of the email. Used to establish if the key is new or old relative to any keys already existing |
The key data from importing the key
{- "data": {
- "added": true,
- "keys": [
- {
- "id": 0,
- "expired": true,
- "hasPrivateKey": true,
- "fingerPrint": "string",
- "userIds": [
- "string"
], - "encryptionKey": true,
- "masterKey": true,
- "validSeconds": 0,
- "revoked": true,
- "creationTime": 0
}
], - "new": true
}, - "error": "string",
- "error_params": [
- "string"
], - "error_id": "string",
- "error_desc": "string",
- "error_stack": [
- "string"
], - "code": "string",
- "categories": "string",
- "category": 0
}
Sets an autocrypt key as verified or not. Only trusted if verified
session required | string A session ID previously obtained from the Appsuite HTTP login module. |
keyids required | string The ID of the key to be verified. Should be fingerprint of main public key |
verified required | boolean True if the user has confirmed this key. Marks the key as verified |
Empty 200 response if success. Otherwise error data
{- "data": {
- "added": true,
- "keys": [
- {
- "id": 0,
- "expired": true,
- "hasPrivateKey": true,
- "fingerPrint": "string",
- "userIds": [
- "string"
], - "encryptionKey": true,
- "masterKey": true,
- "validSeconds": 0,
- "revoked": true,
- "creationTime": 0
}
], - "new": true
}, - "error": "string",
- "error_params": [
- "string"
], - "error_id": "string",
- "error_desc": "string",
- "error_stack": [
- "string"
], - "code": "string",
- "categories": "string",
- "category": 0
}
DEPRECATED, use changepass instead. For new Guest account, assigns new password as well as password reset question/answer.
Data containing necessary information to assign a new password.
question required | string A question to use in the event of a password reset |
answer required | string The required response to the question to verify a password reset. Can be blank if not supplied |
newpass required | string The new password for the new account. If no password reset option, can be blank |
email required | string The email address of the Guest user |
itemId required | string Item Id of the guest email. Must have a valid email item in order to help verify legit password change |
pin | string If the guest email was sent with optional PIN, must be provided here |
New auth response
{- "question": "string",
- "answer": "string",
- "newpass": "string",
- "email": "string",
- "itemId": "string",
- "pin": "string"
}
{- "auth": "string"
}
DEPRECATED. Gets the question to be answered to verify password reset request
email required | string The email to be reset |
Response will contain the question, error, or "nf" if not found
DEPRECATED, use reset instead. Performs a password reset for a Guest
email required | string The email to be reset |
answer required | string The answer to the challenge question |
language | string Language for the user |
templid | integer The template id for the custom layout |
Response will contain 'No Match' or 'OK'
'Error decoding answer', 'Failed to change', or FailNotify
DEPRECATED. First step to reset Guest account. Sends email with temporary token for user
user required | string The email address of the user for the reset |
templid | integer Optional templateId for the user for customization |
A JSON with data:OK if success, else error message
DEPRECATED. Performs the reset of the Guest account. Requires secret token sent to them previously
Data containing necessary information to perform the reset.
resetid required | string The reset token string found in the email sent to the user for verification |
email required | string The email address of the Guest user |
password required | string The new password for the newly created account |
A JSON with data:OK if success, else error message
{- "resetid": "string",
- "email": "string",
- "password": "string"
}
"string"
The authentication module to get authentication token for action and saving the token to the session
Checks with the middleware if a valid authentication token exists within the session
session required | string A session ID previously obtained from the Appsuite HTTP login module. |
Returns an object containing authentication, duration, with possible error.
{- "data": {
- "auth": "string",
- "minutesValid": 0,
- "createdOn": 0
}, - "error": "string",
- "error_params": [
- "string"
], - "error_id": "string",
- "error_desc": "string",
- "error_stack": [
- "string"
], - "code": "string",
- "categories": "string",
- "category": 0
}
Performs a login against the OX Guard Server in order to obtain an authentication token, then saves the token in the user session for specified period of time
session required | string A session ID previously obtained from the Appsuite HTTP login module. |
The new password to authenticate and duration to remember the password
e_password | string The RSA encrypted password of the user's OX Guard key. e_password or password must be provided |
password | string Plaintext password of the user's OX Guard Key. Only use if RSA key not available |
minutesValid | integer Minutes to remember the password. "-1" for single use. "0" for indefinite |
Returns an object containing authentication, duration, with possible error.
{- "e_password": "string",
- "password": "string",
- "minutesValid": 0
}
{- "data": {
- "auth": "string",
- "minutesValid": 0,
- "createdOn": 0
}, - "error": "string",
- "error_params": [
- "string"
], - "error_id": "string",
- "error_desc": "string",
- "error_stack": [
- "string"
], - "code": "string",
- "categories": "string",
- "category": 0
}
Saves an existing authentication token (obtained from a login response) in the user's session for specified period of time.
session required | string A session ID previously obtained from the Appsuite HTTP login module. |
The new password to authenticate and duration to remember the password
auth | string The authentication token to attach to the user's session. |
minutesValid | integer Minutes to remember the authentication token. "-1" for single use. "0" for indefinite |
Returns an object containing authentication, duration, with possible error.
{- "auth": "string",
- "minutesValid": 0
}
{- "data": {
- "auth": "string",
- "minutesValid": 0,
- "createdOn": 0
}, - "error": "string",
- "error_params": [
- "string"
], - "error_id": "string",
- "error_desc": "string",
- "error_stack": [
- "string"
], - "code": "string",
- "categories": "string",
- "category": 0
}
The OX Guard Support API enables administrative access to various functions for maintaining OX Guard from a client in a role as a support employee. A client has to do a BASIC AUTH authentication in order to access the API. Username and password can be configured in the guard-core.properties file.
Resets the OX Guard password of a user's current key. A new password is sent to the user's secondary email address, or the primary email address as fallback.
email required | string Specifies the email of the user whose password should be reset. |
Returns the kind of email address a new generated password was send to. "PRIMARY" or "SECONDARY".
Deletes all keys for given user. Note that deleted keys are not usable anymore but are still available as download if marked as "exposed".
user_id | integer Specifies the user ID of the user whose password should be reset. |
cid | integer Specifies the context ID of the user whose password should be reset. |
string If user_id and cid are omitted, the email parameter can be used to specify the user whose keys should be deleted. |
Returns "OK" if the keys were deleted.
Marks a deleted (but backed up) key as "exposed". If a deleted key is marked as "exposed" it is possible to download the key for a configured amount of time by calling the returned URL.
string The email of the user to expose the deleted keys for. | |
cid | integer The user's context ID. |
Returns an URL pointing to the download of the exposed keys.
Upgrades a guest user to a regular OX Guard user.
email required | string Specifies the email of the guest user to upgrade |
cid required | integer The new user's context ID. |
user_id required | integer The new user's ID. |
Returns "OK" if the guest user was upgraded to a new regular user.