OX Guard API (2.10.2)

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

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

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":
    {
    },
  • "settings":
    {
    }
}

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

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

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

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

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":
    {
    },
  • "error": "string",
  • "error_params":
    [
    ],
  • "error_id": "string",
  • "error_desc": "string",
  • "error_stack":
    [
    ],
  • "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":
    {
    },
  • "error": "string",
  • "error_params":
    [
    ],
  • "error_id": "string",
  • "error_desc": "string",
  • "error_stack":
    [
    ],
  • "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":
    {
    },
  • "error": "string",
  • "error_params":
    [
    ],
  • "error_id": "string",
  • "error_desc": "string",
  • "error_stack":
    [
    ],
  • "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":
    {
    },
  • "error": "string",
  • "error_params":
    [
    ],
  • "error_id": "string",
  • "error_desc": "string",
  • "error_stack":
    [
    ],
  • "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.

Response samples

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

downloadKey

post /oxguard/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
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 as raw ASCII armored data.

setCurrentKey

put /oxguard/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 /oxguard/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: 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

200

A collection of uploaded key rings.

Response samples

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

uploadExternalPublicKey

post /oxguard/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: multipart/form-data
key
required
string <binary>

The ASCII armored data of the key ring.

Responses

200

A collection of imported external key rings.

Response samples

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

getExternalPublicKeys

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

query Parameters
session
required
string

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

keyType
string

Type of key to retrieve. Defaults to uploaded Public Keys. Other example is "autocrypt"

Responses

200

The collection of uploaded external key rings.

Response samples

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

shareExternalPublicKey

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

keyids
required
string

The ids parameter from the ExternalPublicKeyRing object as obtained from the GetExternalPublicKeys request.

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

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

keyids
required
string

The ids parameter from the ExternalPublicKeyRing object as obtained from the GetExternalPublicKeys request.

keyType
string

Type of key to retrieve. Defaults to uploaded Public Keys. Other example is "autocrypt"

Responses

200

An empty response in case the key was deleted.

addUserId

post /oxguard/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 /oxguard/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-, or sub-key to revoke.

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.

e_password
string

The, RSA encrypted, 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 /oxguard/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":
    {
    },
  • "error": "string",
  • "error_params":
    [
    ],
  • "error_id": "string",
  • "error_desc": "string",
  • "error_stack":
    [
    ],
  • "code": "string",
  • "categories": "string",
  • "category": 0
}

getSignatures

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

Gets the signatures for a user's key.

query Parameters
session
required
string

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

keyid
required
integer <int64>

The ID of the key to get a list of signatures for.

subkeys
boolean
Default: false

True to include signatures for subkeys (only if the given keyid belongs to a master key). False to just return the signatures for the given key.

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":
    {
    },
  • "error": "string",
  • "error_params":
    [
    ],
  • "error_id": "string",
  • "error_desc": "string",
  • "error_stack":
    [
    ],
  • "code": "string",
  • "categories": "string",
  • "category": 0
}

putautocrypt

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

Send the autocrpt header to Guard to import or return key details. Client should verify the address in header is part of the mime email

query Parameters
session
required
string

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

add
boolean

If the key should be automatically imported. If false, only key information is returned

confirmed
boolean

True if the user has confirmed this key and wants it added. Marks the key as verified

Request Body schema: application/x-www-form-urlencoded
header
required
string

The value of the autoCrypt header from the MIME email

sent_date
required
string

The sent date of the email. Used to establish if the key is new or old relative to any keys already existing

Responses

200

The key data from importing the key

Response samples

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

Verify autocrypt key

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

Sets an autocrypt key as verified or not. Only trusted if verified

query Parameters
session
required
string

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

keyids
required
string

The ID of the key to be verified. Should be fingerprint of main public key

verified
required
boolean

True if the user has confirmed this key. Marks the key as verified

Responses

200

Empty 200 response if success. Otherwise error data

Response samples

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

guest

This module provides access to guest functionality.

Assigns Password. DEPRECATED. Deprecated

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

DEPRECATED, use changepass instead. For new Guest account, assigns new password as well as password reset question/answer.

Request Body schema: application/json

Data containing necessary information to assign a new password.

question
required
string

A question to use in the event of a password reset

answer
required
string

The required response to the question to verify a password reset. Can be blank if not supplied

newpass
required
string

The new password for the new account. If no password reset option, can be blank

email
required
string

The email address of the Guest user

itemId
required
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

Request samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "question": "string",
  • "answer": "string",
  • "newpass": "string",
  • "email": "string",
  • "itemId": "string",
  • "pin": "string"
}

Response samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "auth": "string"
}

Get reset question. DEPRECATED. Deprecated

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

DEPRECATED. Gets the question to be answered to verify password reset request

query Parameters
email
required
string

The email to be reset

Responses

200

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

Reset password. DEPRECATED. Deprecated

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

DEPRECATED, use reset instead. 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. DEPRECATED. Deprecated

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

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

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

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

Request Body schema: application/json

Data containing necessary information to perform the reset.

resetid
required
string

The reset token string found in the email sent to the user for verification

email
required
string

The email address of the Guest user

password
required
string

The new password for the newly created account

Responses

200

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

Request samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "resetid": "string",
  • "email": "string",
  • "password": "string"
}

Response samples

Content type
application/json
Copy
Expand all Collapse all
"string"

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

get /guard-json?action=auth-token
https://example.com/appsuite/api/guard-json?action=auth-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

200

Returns an object containing authentication, duration, with possible error.

Response samples

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

authorize and save to session

post /guard-json?action=auth-token
https://example.com/appsuite/api/guard-json?action=auth-token

Performs a login against the OX Guard Server in order to obtain an authentication token, then saves the token in the user session for specified 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. e_password or password must be provided

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

200

Returns an object containing authentication, duration, with possible error.

Request samples

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

Response samples

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

Attaches an existing authentication token to the user's session.

put /guard-json?action=auth-token
https://example.com/appsuite/api/guard-json?action=auth-token

Saves an existing authentication token (obtained from a login response) in the user's session for specified 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

auth
string

The authentication token to attach to the user's session.

minutesValid
integer

Minutes to remember the authentication token. "-1" for single use. "0" for indefinite

Responses

200

Returns an object containing authentication, duration, with possible error.

Request samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "auth": "string",
  • "minutesValid": 0
}

Response samples

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

Support API

The OX Guard Support API enables administrative access to various functions for maintaining OX Guard from a client in a role as a support employee. A client has to do a BASIC AUTH authentication in order to access the API. Username and password can be configured in the guard-core.properties file.

reset_password

post /guardsupport/?action=reset_password
https://example.com/appsuite/api/guardsupport/?action=reset_password

Resets the OX Guard password of a user's current key. A new password is sent to the user's secondary email address, or the primary email address as fallback.

query Parameters
email
required
string

Specifies the email of the user whose password should be reset.

Responses

200

Returns the kind of email address a new generated password was send to. "PRIMARY" or "SECONDARY".

delete_user

post /guardsupport/?action=delete_user
https://example.com/appsuite/api/guardsupport/?action=delete_user

Deletes all keys for given user. Note that deleted keys are not usable anymore but are still available as download if marked as "exposed".

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

Specifies the user ID of the user whose password should be reset.

cid
integer

Specifies the context ID of the user whose password should be reset.

email
string

If user_id and cid are omitted, the email parameter can be used to specify the user whose keys should be deleted.

Responses

200

Returns "OK" if the keys were deleted.

expose_key

post /guardsupport/?action=expose_key
https://example.com/appsuite/api/guardsupport/?action=expose_key

Marks a deleted (but backed up) key as "exposed". If a deleted key is marked as "exposed" it is possible to download the key for a configured amount of time by calling the returned URL.

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

The email of the user to expose the deleted keys for.

cid
integer

The user's context ID.

Responses

200

Returns an URL pointing to the download of the exposed keys.

upgrade_guest

post /guardsupport/?action=upgrade_guest
https://example.com/appsuite/api/guardsupport/?action=upgrade_guest

Upgrades a guest user to a regular OX Guard user.

Request Body schema: application/x-www-form-urlencoded
email
required
string

Specifies the email of the guest user to upgrade

cid
required
integer

The new user's context ID.

user_id
required
integer

The new user's ID.

Responses

200

Returns "OK" if the guest user was upgraded to a new regular user.