Threema Work API (1.3.4)

Download OpenAPI specification:Download

Threema Work API is designed to let 3rd-party applications communicate with Threema Work subscriptions. *

All requests are authenticated using an X-API-Key which can be obtained from your management cockpit.
An X-API-Key HTTP header must be sent to indicate which API key is to be used with the request.
The API key must match the remote IP (if specified for the given API key) of the connected HTTP client.

Authentication

apiKey

Security Scheme Type	API Key
Header parameter name:	X-Api-Key

Subscription

Subscription methods provide access to the subscription.

Subscription: Detail

Access to your subscription

Authorizations:

apiKey

Responses

Response Schema: application/json

	Array of objects <application/json> (Link) [ items <application/json> ]
name	string Short description name of the subscription
validUntil	string (DateTime) 24 characters ISO8601 formated date Example: `2017-01-01T00:00:00+0100`
type	string Enum: "basic" "business" "enterprise" "essential" "advanced" "professional" "edu5" Chosen subscription type
licenseAmount	integer Number of purchased licenses

Response samples

200
401

Content type

application/json

{"_links": [{"ref": "detail",
"link": "https://work.threema.ch/api/v1"
},
{"ref": "credentials",
"link": "https://work.threema.ch/api/v1/credentials"
},
{"ref": "users",
"link": "https://work.threema.ch/api/v1/users"
},
{"ref": "logos",
"link": "https://work.threema.ch/api/v1/logos"
},
{"ref": "contacts",
"link": "https://work.threema.ch/api/v1/contacts"
}
],
"name": "My Threema Work subscription",
"validUntil": "2017-01-01T00:00:00+0100",
"type": "professional",
"licenseAmount": 400
}

Subscription: Update

Change the name of the subscription

Authorizations:

apiKey

Request Body schema: application/json

name

required

string [ 1 .. 256 ] characters

New name of the subscription

Responses

Request samples

Payload

Content type

application/json

{"name": "My very nice Threema Work subscription"
}

Response samples

400
401

Content type

application/json

{"message": "Detailed error message"
}

Credentials

Credential methods provide access to the subscription credentials.

Credentials: List

List all credentials of the package

Authorizations:

apiKey

query Parameters

filterUsername	string Filter the credentials by the `username`
pageSize	integer <int32> (PageSizeParameter) [ 1 .. 5000 ] Default: 20 Set the limit the filter result.
page	integer Set to page offset the filter result to a particular record count.

Responses

Response Schema: application/json

	Array of objects <application/json> (Link) [ items <application/json> ]
	Array of objects (Credential) [ items ] Credential List
	object <application/json> (Paging)

Response samples

200
401

Content type

application/json

{"_links": [{"ref": "subscription",
"link": "https://work.threema.ch/api/v1"
}
],
"credentials": [{"_links": [{"ref": "detail",
"link": "https://work.threema.ch/api/v1/credentials/LAow0Rksa"
}
],
"id": "LAow0Rksa",
"username": "alice",
"password": "3mawrk",
"licenseAmount": 0,
"hash": false,
"lock": true
},
{"_links": [{"ref": "detail",
"link": "https://work.threema.ch/api/v1/credentials/pwq4Kslw"
}
],
"id": "pwq4Kslw",
"username": "bob",
"password": null,
"licenseAmount": 0,
"hash": true,
"lock": false
}
],
"paging": {"count": 20,
"total": 400,
"page": 9,
"_links": [{"ref": "detail",
"link": "https://work.threema.ch/api/v1/link-to-resource"
}
]
}
}

Credentials: Create

Create new credentials

Authorizations:

apiKey

Request Body schema: application/json

username required	string [ 1 .. 256 ] characters Unique username
password required	string [ 1 .. 256 ] characters Password of the credential
hash	boolean Default: false If you save the password as hash, there’s no way for you to retrieve it.
licenseCount	integer License count
lock	boolean Once the credentials are in use with a specific ID, they cannot be used in conjunction with any other ID (unless the original ID is either revoked or detached from this subscription).

Responses

Response Headers
Location	string A link to the credential detail resource.

Response Schema: application/json

	Array of objects <application/json> (Link) [ items <application/json> ]
id	string (CredentialsId) Unique id of a credential record
username	string
password	string
licenseAmount	integer
hash	boolean Default: false If you save the password as hash, there’s no way for you to retrieve it.
lock	boolean Once the credentials are in use with a specific ID, they cannot be used in conjunction with any other ID (unless the original ID is either revoked or detached from this subscription).

Request samples

Payload

Content type

application/json

{"username": "bob",
"password": "3mawrk",
"hash": false,
"licenseCount": 1,
"lock": true
}

Response samples

201
400
401
403

Content type

application/json

{"_links": [{"ref": "detail",
"link": "https://work.threema.ch/api/v1/credentials/LAow0Rksa"
},
{"ref": "subscription",
"link": "https://work.threema.ch/api/v1"
}
],
"id": "e7MCEXNCGmRDRX3BF71tJAoAiLVpvsu",
"username": "alice",
"password": "3mawrk",
"licenseAmount": 1,
"hash": true,
"lock": true
}

Credentials: Detail

Show credentials for a specified id

Authorizations:

apiKey

path Parameters

id

required

string (CredentialsId)

Example: e7MCEXNCGmRDRX3BF71tJAoAiLVpvsu

Unique id of a credential record

Responses

Response Schema: application/json

	Array of objects <application/json> (Link) [ items <application/json> ]
id	string (CredentialsId) Unique id of a credential record
username	string
password	string
licenseAmount	integer
hash	boolean Default: false If you save the password as hash, there’s no way for you to retrieve it.
lock	boolean Once the credentials are in use with a specific ID, they cannot be used in conjunction with any other ID (unless the original ID is either revoked or detached from this subscription).

Response samples

200
400
401
404

Content type

application/json

{"_links": [{"ref": "detail",
"link": "https://work.threema.ch/api/v1/credentials/LAow0Rksa"
},
{"ref": "subscription",
"link": "https://work.threema.ch/api/v1"
}
],
"id": "e7MCEXNCGmRDRX3BF71tJAoAiLVpvsu",
"username": "alice",
"password": "3mawrk",
"licenseAmount": 1,
"hash": true,
"lock": true
}

Credentials: Update

Update the username and password of a specified id

Authorizations:

apiKey

path Parameters

id

required

string (CredentialsId)

Example: e7MCEXNCGmRDRX3BF71tJAoAiLVpvsu

Unique id of a credential record

Request Body schema: application/json

username required	string [ 1 .. 256 ] characters Unique username
password required	string [ 1 .. 256 ] characters Password of the credential
hash	boolean Default: false If you save the password as hash, there’s no way for you to retrieve it.
lock	boolean Once the credentials are in use with a specific ID, they cannot be used in conjunction with any other ID (unless the original ID is either revoked or detached from this subscription).

Responses

Request samples

Payload

Content type

application/json

{"username": "bob",
"password": "3mawrk",
"hash": true,
"lock": true
}

Response samples

400
401
404

Content type

application/json

{"message": "Detailed error message"
}

Credentials: Remove

Remove credentials of a specified id

Authorizations:

apiKey

path Parameters

id

required

string (CredentialsId)

Example: e7MCEXNCGmRDRX3BF71tJAoAiLVpvsu

Unique id of a credential record

Responses

Response samples

400
401
404

Content type

application/json

{"message": "Detailed error message"
}

Users

Subscription methods provide access to the subscription users.

Users: List

List all users of the package

Authorizations:

apiKey

query Parameters

filterCredential	string Filter the users by the `id` of the used `Credential`
filterUsername	string Filter the users by the `username` of the used `Credential`
filterQuery	string Search the users
pageSize	integer <int32> (PageSizeParameter) [ 1 .. 5000 ] Default: 20 Set the limit the filter result.
page	integer Set to page offset the filter result to a particular record count.

Responses

Response Schema: application/json

	Array of objects <application/json> (Link) [ items <application/json> ]
	Array of objects (User) [ items ] User List
	object <application/json> (Paging)

Response samples

200
400
401

Content type

application/json

{"_links": [{"ref": "subscription",
"link": "https://work.threema.ch/api/v1"
}
],
"users": [{"_links": [{"link": "https://work.threema.ch/api/v1/users/USER001",
"ref": "detail"
},
{"link": "https://work.threema.ch/api/v1/credentials/LAow0Rksa",
"ref": "credential"
}
],
"id": "USER001",
"lastCheck": "2021-12-01T00:00:00+0100",
"createdAt": "2017-01-01T00:00:00+0100",
"nickname": "Alice",
"firstName": "Al",
"lastName": "Ice",
"csi": "AI000001",
"category": "Marketing",
"version": "android - 3.1k"
},
{"_links": [{"link": "https://work.threema.ch/api/v1/users/USER002",
"ref": "detail"
},
{"link": "https://work.threema.ch/api/v1/credentials/Kpsow3lSdf",
"ref": "credential"
}
],
"id": "USER002",
"lastCheck": "2021-12-01T00:00:00+0100",
"createdAt": "2017-01-01T00:00:00+0100",
"nickname": "Bob",
"firstName": "B",
"lastName": "Ob",
"csi": "AI000002",
"category": "IT",
"version": "ios - 2.9k"
}
],
"paging": {"count": 20,
"total": 400,
"page": 9,
"_links": [{"ref": "detail",
"link": "https://work.threema.ch/api/v1/link-to-resource"
}
]
}
}

User: Detail

Show a user, selected by threemaId

Authorizations:

apiKey

path Parameters

threemaId

required

string (ThreemaId)

Example: B4UXXX11

Responses

Response Schema: application/json

	Array of objects <application/json> (Link) [ items <application/json> ]
id	string (ThreemaId)
nickname	string Nickname, chosen by the user in the Threema App
firstName	string First name of the user, configured by the MDM system.
lastName	string Last name of the user, configured by the MDM system.
csi	string Any value (e.g. internal username), configured by the MDM system.
category	string User category (e.g. group, department), configured by the MDM system.
version	string Used Version * Example: `android - 3.1k` \| OS \| Separator \| App Version \| \|---------\|-----------\|-------------\| \| `android` \| `-` \| `3.1k` \|
lastCheck	string (DateTime) 24 characters ISO8601 formated date Example: `2017-01-01T00:00:00+0100`
createdAt	string (DateTime) 24 characters ISO8601 formated date Example: `2017-01-01T00:00:00+0100`

Response samples

200
400
401
404

Content type

application/json

{"_links": [{"ref": "detail",
"link": "https://work.threema.ch/api/v1/users/ECHOECHO"
},
{"ref": "subscription",
"link": "https://work.threema.ch/api/v1"
},
{"ref": "credential",
"link": "https://work.threema.ch/api/v1/credentials/LAow0Rksa"
}
],
"id": "B4UXXX11",
"nickname": "Alice",
"firstName": "Al",
"lastName": "Ice",
"csi": "AI000001",
"category": "Marketing",
"version": "android - 3.1k",
"lastCheck": "2017-01-01T00:00:00+0100",
"createdAt": "2017-01-01T00:00:00+0100"
}

User: Remove

Revoke a user(Threema ID), selected by threemaId