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.
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.
ox_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.
{- "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
}
}
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 | string The current password of the key which will be replaced. |
newpass | string The new password to set. |
Returns an object containing new authentication information.
{- "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.
"string"
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 | string The password of the user's current OX Guard key. |
string The new secondary email address to set. |
"OK" or an error message in case of an error.
"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.
"string"
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. |
name required | string The user's name which will be part of the key identity. |
The new created key ring.
{- "data": {
- "userId": 0,
- "contextId": 0,
- "current": true,
- "publicRing": {
- "ring": "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. |
An empty response in case the key has been deleted.
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,
- "publicRing": {
- "ring": "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 | string The 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,
- "publicRing": {
- "ring": "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 | string The 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 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. |
An empty response in case the key rings have been imported.
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 The ASCII armored data of the key ring. |
An empty response in case the key rings have been imported.
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.
The collection of uploaded external key rings.
{- "data": {
- "externalPublicKeyRings": [
- {
- "ids": "string",
- "shareLevel": 0,
- "inline": true,
- "shared": true,
- "publicRing": {
- "ring": "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. |
ids 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. |
ids required | string The ids parameter from the ExternalPublicKeyRing object as obtained from the GetExternalPublicKeys request. |
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 key to revoke. |
password required | string The 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",
- "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
}
Sets user specific PGP settings. The current active settings are returned within the login-response.
session required | string A session ID previously obtained from the Appsuite HTTP login module. |
The settings to apply for all keys owned by the user.
pgpdefault | boolean True to encrypt emails by default when composing, False to not encrypt emails by default. |
pgpsign | boolean True to sign emails by default when composing, False to not sign emails by default. |
inline | boolean True to use PGP inline by default when sending encrypted or signed emails, False to use PGP/MIME by default. |
"done" if the settings have been stored, an error message otherwise.
"string"
For new Guest account, assigns new password as well as password reset question/answer
Data containing necessary information to assign a new password.
question | string A question to use in the event of a password reset |
answer | string The required response to the question to verify a password reset. Can be blank if not supplied |
newpass | string The new password for the new account. If no password reset option, can be blank |
string The email address of the Guest user | |
itemId | 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
{- "auth": "string"
}
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
Changes guest password
session required | string A session obtained during the login throug the Guest login |
auth required | string The authorization code provided from previous login |
Data containing necessary information to change a password.
oldpass | string The old password |
newpass | string The new password for the new account. If no password reset option, can be blank |
question | string A question to use in the event of a password reset. May be blank if not changing |
answer | string The required response to the question to verify a password reset. Can be blank if not supplied |
New auth response
{- "auth": "string"
}
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
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
Performs the reset of the Guest account. Requires secret token sent to them previously
Data containing necessary information to perform the reset.
resetid | string The reset token string found in the email sent to the user for verification |
string The email address of the Guest user | |
password | string The new password for the newly created account |
"OK" or an error message in case of an error.
"string"
Gets decoded email
session required | string A session obtained during the login throug the Guest login |
auth required | string The authorization code provided from previous login |
Data containing necessary information to change a password.
item | string The itemId of the Guest email |
Email Json
Gets and email attachment
session required | string A session obtained during the login throug the Guest login |
email required | string Guard email id |
auth required | string required authorization token |
attname required | string name of the attachment |
language required | string language of the UI |
cid required | integer The context ID of the user |
download | boolean If true, Content-disposition sent so that file is saved |
Response will contain decoded attachment stream. If download set, will have Content-Disposition set to "attachment" with the filename.
Gets image contained in the body of an email (cid image)
session required | string A session obtained during the login throug the Guest login |
email required | string Guard email id |
auth required | string required authorization token |
content_id required | string the image cid (image id) |
cid required | integer The context ID of the user |
Response will contain decoded attachment stream.
Guest emails are only stored for a limited time. After that, they need to be re-uploaded.
session required | string A session obtained during the login throug the Guest login |
auth required | string The authorization code provided from previous login |
itemid required | string The itemId for the email |
OK if success
'Not decodable' if password wrong for email or key unavailable, or other error message