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.
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). |
{- "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. |
{- "auth": "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. |
"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. |
"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. |
{- "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. |
{- "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. |
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. |
{- "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') |
{- "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') |
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. |
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. |
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.
{- "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". |
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. |
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 |
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. |
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). |
{- "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. |
"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 |
{- "auth": "string"
}
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 |
{- "auth": "string"
}
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 |
"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 |
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 |
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 |
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 |
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. |
{- "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 speficied 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 |
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 |
{- "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
}