Documentation Powered by ReDoc

OX Guard API (2.10.3)

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

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.

See also auth-token for creating and attaching an authentication token to the user's session.

query Parameters
session
required
string

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

Request Body schema: application/json

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

Request samples

Content type
application/json
{
  • "encr_password": "string",
  • "language": "en_EN"
}

Response samples

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

logout

Destroys any Guard sessions for the user.

query Parameters
session
required
string

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

Responses

guest login

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

Request Body schema: application/json

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.

Responses

Request samples

Content type
application/json
{
  • "username": "string",
  • "password": "string"
}

Response samples

Content type
application/json
{
  • "productName": "string",
  • "auth": "string",
  • "recoveryAvail": true,
  • "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/json

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.

Responses

Request samples

Content type
application/json
{
  • "oldpass": "string",
  • "newpass": "string"
}

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

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/json

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.

Responses

Request samples

Content type
application/json
{
  • "password": "string",
  • "email": "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

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

email
string

Optional second email address to be used for password resets

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. Can be omitted if e_password is used or if public key only

e_password
string

The, RSA encrypted, password of the private key.

Responses

getContactKeys

Gets the collection of public PGP key rings associated with a contact.

query Parameters
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

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
}

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

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

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: multipart/form-data
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.

Responses

Response samples

Content type
application/json
{
  • "data": {