OX Guard API (2.10)

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

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

200

Returns an object containing authentication information and settings.

Request samples

Payload

Content type

application/json

Copy

Expand all Collapse all


{"encr_password": "string",
"language": "en_EN"
}

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

logout

get /oxguard/login?action=logout

https://example.com/appsuite/api/oxguard/login?action=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

200

Returns OK if successful, otherwise error JSON

guest login

post /oxguard/login?action=guest

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

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

200

guest login response

Request samples

Payload

Content type

application/json

Copy

Expand all Collapse all


{"username": "string",
"password": "string"
}

Response samples

Content type

application/json

Copy

Expand all Collapse all


{"productName": "string",
"auth": "string",
"recoveryAvail": true,
"settings": 
{"min_password_length": 0
}
}

changepass

post /oxguard/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/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

200

Returns an object containing new authentication information.

Request samples

Payload

Content type

application/json

Copy

Expand all Collapse all


{"oldpass": "string",
"newpass": "string"
}

Response samples

Content type

application/json

Copy

Expand all Collapse all


{"auth": "string"
}

secondary

get /oxguard/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.

changesecondary

post /oxguard/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/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

200

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

Request samples

Payload

Content type

application/json

Copy

Expand all Collapse all


{"password": "string",
"email": "string"
}

reset

get /oxguard/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.

keys

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

hasKey

get /oxguard/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 /oxguard/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. 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

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

200

An empty JSON response in case the key has been deleted.

getContactKeys

get /oxguard/keys?action=getContactKeys

https://example.com/appsuite/api/oxguard/keys?action=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

200

A collection of the public key rings associated with a contact.

Response samples

Content type

application/json

Copy

Expand all Collapse all


{"data": 
{"externalPublicKeyRings": 
[
{"ids": "string",
"shareLevel": 0,
"inline": true,
"owned": true,
"shared": true,
"guardKey": 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
}

getKeys

get /oxguard/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 /oxguard/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 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

200

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