OX Guard API (2.6.0)

Download OpenAPI specification:Download

Open-Xchange GmbH: info@open-xchange.com URL: https://www.open-xchange.com/

Documentation of the Open-Xchange OX Guard HTTP API

login

post /login=action=login

https://example.com/appsuite/api/oxguard/login=action=login

Performs a login against the OX Guard Server in order to obtain an authentication token and various user specific settings.

query Parameters

session

required

string

A session ID previously obtained from the Appsuite HTTP login module.

Request Body schema: application/x-www-form-urlencoded

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).

Responses

200

Returns an object containing authentication information and settings.

Response samples

Content type

application/json

Copy

Expand all Collapse all


{"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
}
}

changepass

post /login=action=changepass

https://example.com/appsuite/api/oxguard/login=action=changepass

Changes the password of the user's current key

query Parameters

session

required

string

A session ID previously obtained from the Appsuite HTTP login module.

Request Body schema: application/x-www-form-urlencoded

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.

Responses

200

Returns an object containing new authentication information.

Response samples

Content type

application/json

Copy

Expand all Collapse all


{"auth": "string"
}

secondary

get /login=action=secondary

https://example.com/appsuite/api/oxguard/login=action=secondary

Gets the user's secondary email address where password reset information will be sent to.

query Parameters

session

required

string

A session ID previously obtained from the Appsuite HTTP login module.

Responses

200

Returns the user's secondary email address or an empty response if no secondary email address is set for the user.

Response samples

Content type

application/json

Copy

Expand all Collapse all

"string"

changesecondary

post /login=action=changesecondary

https://example.com/appsuite/api/oxguard/login=action=changesecondary

Sets the user's secondary email address where password reset information will be sent to.

query Parameters

session

required

string

A session ID previously obtained from the Appsuite HTTP login module.

Request Body schema: application/x-www-form-urlencoded

Data containing necessary information in order to change the user's password.

password	string The password of the user's current OX Guard key.
email	string The new secondary email address to set.

Responses

200

"OK" or an error message in case of an error.

Response samples

Content type

application/json

Copy

Expand all Collapse all

"string"

reset

get /login=action=reset

https://example.com/appsuite/api/oxguard/login=action=reset

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.

query Parameters

session

required

string

A session ID previously obtained from the Appsuite HTTP login module.

Responses

200

"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.

Response samples

Content type

application/json

Copy

Expand all Collapse all

"string"

keys

The keys module provides functionality to create, receive and manage PGP key pairs.

hasKey

get /keys?action=hasKey

https://example.com/appsuite/api/oxguard/keys?action=hasKey

Checks if the user has at least one public and/or private PGP key available.

query Parameters

session

required

string

A session ID previously obtained from the Appsuite HTTP login module.

Responses

200

A JSON object which contains if the user has a private and/or public key setup.

Response samples

Content type

application/json

Copy

Expand all Collapse all


{"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
}

create

post /keys?action=create

https://example.com/appsuite/api/oxguard/keys?action=create

Creates a new PGP key ring for the user and marks the new key ring as "current".

query Parameters

session

required

string

A session ID previously obtained from the Appsuite HTTP login module.

Request Body schema: application/x-www-form-urlencoded

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.

Responses

200

The new created key ring.

Response samples

Content type

application/json

Copy

Expand all Collapse all


{"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
}

delete

post /keys?action=delete

https://example.com/appsuite/api/oxguard/keys?action=delete

Deletes a specific PGP key ring

query Parameters

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.

Request Body schema: application/x-www-form-urlencoded

password

required

string

The password of the private key.

Responses

200

An empty response in case the key has been deleted.

getKeys

get /keys?action=getKeys

https://example.com/appsuite/api/oxguard/keys?action=getKeys

Gets the the user's collection of public PGP key rings.

query Parameters

session

required

string

A session ID previously obtained from the Appsuite HTTP login module.

Responses

200

A collection of the user's public key rings.

Response samples

Content type

application/json

Copy

Expand all Collapse all


{"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
}

getKey

post /keys?action=getKey

https://example.com/appsuite/api/oxguard/keys?action=getKey

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.

query Parameters

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.

Request Body schema: application/x-www-form-urlencoded

password

string

The password of the private key (if keyType is set to 'private' or 'public_private')

Responses

200

The public and/or private part of the specified key ring.

Response samples

Content type

application/json

Copy

Expand all Collapse all


{"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
}

downloadKey

post /keys?action=downloadKey

https://example.com/appsuite/api/oxguard/keys?action=downloadKey

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.

query Parameters

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.

Request Body schema: application/x-www-form-urlencoded

password

string

The password of the private key (if keyType is set to 'private' or 'public_private')

Responses

200

The public and/or private part of the specified key ring as raw ASCII armored data.

setCurrentKey

put /keys?action=setCurrentKey

https://example.com/appsuite/api/oxguard/keys?action=setCurrentKey

Marks a Guard PGP key ring as "current".

query Parameters

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".

Responses

200

An empty response in case the key was successfully marked as current.

upload

post /keys?action=upload

https://example.com/appsuite/api/oxguard/keys?action=upload

Uploads a new ASCII armored key ring to OX Guard. The key ring can contain public and/or private keys.

query Parameters

session

required

string

A session ID previously obtained from the Appsuite HTTP login module.

Request Body schema: application/x-www-form-urlencoded

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.

Responses

200

An empty response in case the key rings have been imported.

uploadExternalPublicKey

post /keys?action=uploadExternalPublicKey

https://example.com/appsuite/api/oxguard/keys?action=uploadExternalPublicKey

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.

query Parameters

session

required

string

A session ID previously obtained from the Appsuite HTTP login module.

Request Body schema: application/x-www-form-urlencoded

key

required

string

The ASCII armored data of the key ring.

Responses

200

An empty response in case the key rings have been imported.

getExternalPublicKeys

get /keys?action=getExternalPublicKeys

https://example.com/appsuite/api/oxguard/keys?action=getExternalPublicKeys

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.

Responses

200

The collection of uploaded external key rings.

Response samples

Content type

application/json

Copy

Expand all Collapse all


{"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
}

shareExternalPublicKey

put /keys?action=shareExternalPublicKey

https://example.com/appsuite/api/oxguard/keys?action=shareExternalPublicKey

Marks an uploaded external recipient key as shared or as not shared. An external public key which is marked as shared can be accessed from other OX Guard users in the same context.

query Parameters

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.
shared required	boolean True, to mark the key ring as "shared", False to mark it as "not shared".

Responses

200

An empty response in case the key was marked as shared.

InlineExternalPublicKey

put /keys?action=InlineExternalPublicKey

https://example.com/appsuite/api/oxguard/keys?action=InlineExternalPublicKey

Marks an uploaded external recipient key as "inline". An external public key which is marked as "inline" produces PGP/INLNE email encryption by default.

query Parameters

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".

Responses

200

An empty response in case the key was marked as inline.

DeleteExternalPublicKey

delete /keys?action=DeleteExternalPublicKey

https://example.com/appsuite/api/oxguard/keys?action=DeleteExternalPublicKey

Deletes an uploaded external recipient key.

query Parameters

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.

Responses

200

An empty response in case the key was deleted.

addUserId

put /keys?action=addUserId

https://example.com/appsuite/api/oxguard/keys?action=addUserId

Adds a new user ID "name " to the given key ring.

query Parameters

session

required

string

A session ID previously obtained from the Appsuite HTTP login module.

Request Body schema: application/x-www-form-urlencoded

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 ".

Responses

200

An empty response in case the key was successfully marked as current.

revoke

post /keys?action=revoke

https://example.com/appsuite/api/oxguard/keys?action=revoke

Reovkes a PGP key ring.

query Parameters

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.

Request Body schema: application/x-www-form-urlencoded

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.

Responses

200

An empty response in case the key was revoked.

getRecipKey

get /keys?action=getRecipKey

https://example.com/appsuite/api/oxguard/keys?action=getRecipKey

Queries the public key of a recipient.

query Parameters

session required	string A session ID previously obtained from the Appsuite HTTP login module.
email	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).

Responses

200

The public key ring of the recipient and some additional meta data.

Response samples

Content type

application/json

Copy

Expand all Collapse all


{"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
}

settings

The settings module provides functionality for changing user related PGP options.

set

post /settings=action=set

https://example.com/appsuite/api/oxguard/settings=action=set

Sets user specific PGP settings. The current active settings are returned within the login-response.

query Parameters

session

required

string

A session ID previously obtained from the Appsuite HTTP login module.

Request Body schema: application/x-www-form-urlencoded

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.

Responses

200

"done" if the settings have been stored, an error message otherwise.

Response samples

Content type

application/json

Copy

Expand all Collapse all

"string"

guest

This module provides access to guest functionality.

Assigns Password

post /guest?action=firstpass

https://example.com/appsuite/api/oxguard/guest?action=firstpass

For new Guest account, assigns new password as well as password reset question/answer

Request Body schema: application/x-www-form-urlencoded

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
email	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

Responses

200

New auth response

Response samples

Content type

application/json

Copy

Expand all Collapse all


{"auth": "string"
}

Get reset question

get /guest?action=getquestion

https://example.com/appsuite/api/oxguard/guest?action=getquestion

Gets the question to be answered to verify password reset request

query Parameters

required

string

The email to be reset

Responses

200

Response will contain the question, error, or "nf" if not found

Change Password

post /guest?action=changepass

https://example.com/appsuite/api/oxguard/guest?action=changepass

Changes guest password

query Parameters

session required	string A session obtained during the login throug the Guest login
auth required	string The authorization code provided from previous login

Request Body schema: application/x-www-form-urlencoded

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

Responses

200

New auth response

Response samples

Content type

application/json

Copy

Expand all Collapse all


{"auth": "string"
}

Reset password

get /guest?action=resetpassword

https://example.com/appsuite/api/oxguard/guest?action=resetpassword

Performs a password reset for a Guest

query Parameters

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

Responses

200

Response will contain 'No Match' or 'OK'

406

'Error decoding answer', 'Failed to change', or FailNotify

Guest account reset, step 1

get /guest?action=resetaccount

https://example.com/appsuite/api/oxguard/guest?action=resetaccount

First step to reset Guest account. Sends email with temporary token for user

query Parameters

user required	string The email address of the user for the reset
templid	integer Optional templateId for the user for customization

Responses

200

A JSON with data:OK if success, else error message

Perform reset of Guest account

post /guest?action=doresetaccount

https://example.com/appsuite/api/oxguard/guest?action=doresetaccount

Performs the reset of the Guest account. Requires secret token sent to them previously

Request Body schema: application/x-www-form-urlencoded

Data containing necessary information to perform the reset.

resetid	string The reset token string found in the email sent to the user for verification
email	string The email address of the Guest user
password	string The new password for the newly created account

Responses

200

"OK" or an error message in case of an error.

Response samples

Content type

application/json

Copy

Expand all Collapse all

"string"

Get decoded email

post /guest?action=getmail

https://example.com/appsuite/api/oxguard/guest?action=getmail

Gets decoded email

query Parameters

session required	string A session obtained during the login throug the Guest login
auth required	string The authorization code provided from previous login

Request Body schema: application/x-www-form-urlencoded

Data containing necessary information to change a password.

item	string The itemId of the Guest email

Responses

200

Email Json

Gets email attachment

get /guest?action=getattach

https://example.com/appsuite/api/oxguard/guest?action=getattach

Gets and email attachment

query Parameters

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

Responses

200

Response will contain decoded attachment stream. If download set, will have Content-Disposition set to "attachment" with the filename.

Gets email image

get /guest?action=getattachcid

https://example.com/appsuite/api/oxguard/guest?action=getattachcid

Gets image contained in the body of an email (cid image)

query Parameters

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

Responses

200

Response will contain decoded attachment stream.

Uploads email to cache

post /guest?action=upload

https://example.com/appsuite/api/oxguard/guest?action=upload

Guest emails are only stored for a limited time. After that, they need to be re-uploaded.

query Parameters

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

Responses

200

OK if success

406

'Not decodable' if password wrong for email or key unavailable, or other error message