OX Guard API (2.8.0)

Download OpenAPI specification:Download

Documentation of the Open-Xchange OX Guard HTTP API


login

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.

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.

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

Responses

Response samples

Content type
application/json
{
  • "server": "string",
  • "cid": 0,
  • "primaryEmail": "string",
  • "pubKey": "string",
  • "auth": "string",
  • "recoveryAvail": true,
  • "lang": {
    },
  • "settings": {
    }
}

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

Response samples

Content type
application/json
{
  • "auth": "string"
}

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

Response samples

Content type
application/json
"string"

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

Response samples

Content type
application/json
"string"

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

Response samples

Content type
application/json
"string"

keys

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

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

Response samples

Content type
application/json
{
  • "data": {
    },
  • "error": "string",
  • "error_params": [
    ],
  • "error_id": "string",
  • "error_desc": "string",
  • "error_stack": [
    ],
  • "code": "string",
  • "categories": "string",
  • "category": 0
}

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

Response samples

Content type
application/json
{
  • "data": {
    },
  • "error": "string",
  • "error_params": [
    ],
  • "error_id": "string",
  • "error_desc": "string",
  • "error_stack": [
    ],
  • "code": "string",
  • "categories": "string",
  • "category": 0
}

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

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

Response samples

Content type
application/json
{
  • "data": {
    },
  • "error": "string",
  • "error_params": [
    ],
  • "error_id": "string",
  • "error_desc": "string",
  • "error_stack": [
    ],
  • "code": "string",
  • "categories": "string",
  • "category": 0
}

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

Response samples

Content type
application/json
{
  • "data": {
    },
  • "error": "string",
  • "error_params": [
    ],
  • "error_id": "string",
  • "error_desc": "string",
  • "error_stack": [
    ],
  • "code": "string",
  • "categories": "string",
  • "category": 0
}

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

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

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

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

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

Response samples

Content type
application/json
{
  • "data": {
    },
  • "error": "string",
  • "error_params": [
    ],
  • "error_id": "string",
  • "error_desc": "string",
  • "error_stack": [
    ],
  • "code": "string",
  • "categories": "string",
  • "category": 0
}

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

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

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

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

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

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

Response samples

Content type
application/json
{
  • "data": {
    },
  • "error": "string",
  • "error_params": [
    ],
  • "error_id": "string",
  • "error_desc": "string",
  • "error_stack": [
    ],
  • "code": "string",
  • "categories": "string",
  • "category": 0
}

settings

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

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

Response samples

Content type
application/json
"string"

guest

This module provides access to guest functionality.

Assigns Password

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

Response samples

Content type
application/json
{
  • "auth": "string"
}

Get reset question

Gets the question to be answered to verify password reset request

query Parameters
email
required
string

The email to be reset

Responses

Change Password

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

Response samples

Content type
application/json
{
  • "auth": "string"
}

Reset password

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

Guest account reset, step 1

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

Perform reset of Guest account

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

Response samples

Content type
application/json
"string"

Get decoded email

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

Gets email attachment

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

Gets email image

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

Uploads email to cache

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

auth

The authentication module to get authentication token for action and saving the token to the session

Check if the session has a valid authentication token

Checks with the middleware if a valid authentication token exists within the session

query Parameters
session
required
string

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

Responses

Response samples

Content type
application/json
{
  • "data": {
    },
  • "error": "string",
  • "error_params": [
    ],
  • "error_id": "string",
  • "error_desc": "string",
  • "error_stack": [
    ],
  • "code": "string",
  • "categories": "string",
  • "category": 0
}

authorize and save to session

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

query Parameters
session
required
string

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

Request Body schema: application/json

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

Responses

Request samples

Content type
application/json
{
  • "e_password": "string",
  • "password": "string",
  • "minutesValid": 0
}

Response samples

Content type
application/json
{
  • "data": {
    },
  • "error": "string",
  • "error_params": [
    ],
  • "error_id": "string",
  • "error_desc": "string",
  • "error_stack": [
    ],
  • "code": "string",
  • "categories": "string",
  • "category": 0
}