User API specification (3.1.3)

Download OpenAPI specification:Download

The user service implements all user functions for GroupAlarm.

Authentication

API_Token

To use this API, you need an API-Token from the RBAC settings of your GroupAlarm organization. Place the token inside the HTTP-Header API-Token for every request, otherwise the API will return an "401 Unauthorized" error for your request.

Security Scheme Type API Key
Header parameter name: API-TOKEN

Personal-Access-Token

To use this API, you need a Personal Access Token from your profile settings. Place the token inside the HTTP-Header Personal-Access-Token for every request, otherwise the API will return an "401 Unauthorized" error for your request.

Security Scheme Type API Key
Header parameter name: Personal-Access-Token

auth

Resends the activation email of the requesting user if the account is not activated yet.

Responses

200

email successfully re-sent or account is already activated

400

malformed request, e.g. user is not logged in

500

unexpected error

post /auth/activation
https://app.groupalarm.com/api/v1/auth/activation

Login

Handles the user login and returns a user payload with JWT token

query Parameters
chat_token_platform
string

Determines, for which platform the intercom chat token will be generated. Should be "android", "ios" or empty.

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

The email for this account

password
required
string

The password for this account

mfa
string

The user's current mfa code. This code is required if the user enabled mfa for his account, otherwise it can be left empty. To figure out if the user has mfa enabled, you need to login with username and password first. A http 401 error containing "MFA required" allows you to ask the user a current mfa code. Sending username and password again with the mfa code will finalize the login.

Responses

200

user payload with token

401

email or password incorrect / invalid or missing mfa code / user invitation pending

500

error generating token

post /auth/login
https://app.groupalarm.com/api/v1/auth/login

Response samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "active": true,
  • "availablePreference": true,
  • "avatarURL": "string",
  • "chatToken": "string",
  • "editable": true,
  • "email": "string",
  • "id": 0,
  • "name": "string",
  • "pending": true,
  • "registrationDate": "2020-11-25T17:12:48Z",
  • "surname": "string",
  • "token": "string"
}

email-change

Return the current change request for the email-address of your personal user account.

Responses

200

currently open request

400

received invalid data, check error message for more information

404

no open request found

500

unexpected error

get /auth/change-email
https://app.groupalarm.com/api/v1/auth/change-email

Create a change request for the email-address of your personal user account.

Must include the new email-address and a current mfa-code if mfa is enabled.

Request Body schema: application/json
mfaCode
string

current mfa-code is required if mfa is enabled for the user's account

newEmail
required
string

new email-address for the user's account

Responses

200

request successfully created, check your email inbox to confirm the change

400

received invalid data or pre-checks failed, check error message for more information

500

unexpected error

post /auth/change-email
https://app.groupalarm.com/api/v1/auth/change-email

Request samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "mfaCode": "string",
  • "newEmail": "string"
}

Abort the current change request for the email-address of your personal user account.

Responses

200

currently open request successfully aborted

400

received invalid data, check error message for more information

404

no open request found

500

unexpected error

delete /auth/change-email
https://app.groupalarm.com/api/v1/auth/change-email

invitation-config

GetInvitationText

Get the organization's saved invitation text configuration

Responses

200

custom invitation text configuration

400

missing or invalid data

403

rbac check failed

404

no configuration found

500

unexpected error

get /invite/config/text/{organizationID}
https://app.groupalarm.com/api/v1/invite/config/text/{organizationID}

Response samples

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

SetInvitationText

Set the organization's invitation text configuration

Request Body schema: application/json
organization_id
integer <int64>
text
string

Responses

200

configuration saved successfully

400

missing or invalid data

500

unexpected error

put /invite/config/text/{organizationID}
https://app.groupalarm.com/api/v1/invite/config/text/{organizationID}

Request samples

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

mfa

MFAIsActive

Check if the current user has MFA enabled or not

Responses

200

check was successfully completed

400

missing user id in auth token

500

unexpected error

get /mfa
https://app.groupalarm.com/api/v1/mfa

Response samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "enabled": true
}

MFACreate

Creates a new, disabled MFA config for the current user

Responses

200

config successfully created

400

missing user id in auth token

500

unexpected error

put /mfa
https://app.groupalarm.com/api/v1/mfa

Response samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "image":
    [
    ],
  • "secret": "string",
  • "url": "string"
}

MFAEnable

Enables a new MFA config for the current user

query Parameters
code
required
string

current MFA code

Responses

200

config successfully enabled

400

missing user id in auth token

500

unexpected error

post /mfa
https://app.groupalarm.com/api/v1/mfa

MFADisable

Disables the MFA config for the current user

query Parameters
code
required
string

current MFA code

Responses

200

config successfully disabled

400

missing user id in auth token

500

unexpected error

delete /mfa
https://app.groupalarm.com/api/v1/mfa

MFAGenerateBackupCodes

Creates ten new, one-time-use backup codes

Responses

200

codes successfully created

400

missing user id in auth token

500

unexpected error

get /mfa/backup
https://app.groupalarm.com/api/v1/mfa/backup

Response samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "backupCodes":
    [
    ]
}

user

Deletes the current user irreversibly.

Can only be used after leaving all organizations.

Responses

200

user was successfully deleted

400

parameters missing or in wrong format

403

user is still a member of an organization

500

unexpected error

delete /user
https://app.groupalarm.com/api/v1/user

GetUser

Gets the complete user payload from the passed JWT token

query Parameters
chat_token_platform
string

Determines, for which platform the intercom chat token will be generated. Should be "android", "ios" or empty.

Responses

200

complete user payload for JWT token for queried email

403

Bearer token couldn't be parsed

422

Token claims couldn't be parsed

500

unexpected error

get /user/
https://app.groupalarm.com/api/v1/user/

Response samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "active": true,
  • "availablePreference": true,
  • "avatarURL": "string",
  • "chatToken": "string",
  • "editable": true,
  • "email": "string",
  • "id": 0,
  • "name": "string",
  • "pending": true,
  • "registrationDate": "2020-11-25T17:12:48Z",
  • "surname": "string",
  • "token": "string"
}

UpdateUser

Updates the user profile

Request Body schema: application/json

passed user update payload with new user preferences

organizationId
integer <int64>

id of the editing organization not needed if user is editing himself

user
required
object (User)

User is the comprehensive data structure containing all data of a single user

Responses

200

user was successfully updated

403

user can't be edited from a different organization or user doesn't want to be edited by an organization administrator

500

unexpected error

put /user/
https://app.groupalarm.com/api/v1/user/

Request samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "organizationId": 0,
  • "user":
    {
    }
}

InviteUser

Invites an existing or new user to an organization and sends an invitation email to the passed address

Request Body schema: application/json

invitation payload

createNewLabels
boolean

If set to true while importing a user with a label name but not an id, we will automatically create and assign this label. This setting will only work in conjunction with MapLabelsByName.

mapLabelsByName
boolean

If set to true while importing a user with a label name but not an id, we will try to find a label with this name and assign it.

organization
required
object (Organization)

Organization defines an organization payload

users
required
Array of objects (BulkUserElement)

array of user bulk elements

Responses

200

user was successfully invited

400

user invite payload is missing or in the wrong format

500

unexpected error

post /user/invite
https://app.groupalarm.com/api/v1/user/invite

Request samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "createNewLabels": true,
  • "mapLabelsByName": true,
  • "organization":
    {
    },
  • "users":
    [
    ]
}

Response samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "availablePreference": true,
  • "availableStatus": 0,
  • "avatarURL": "string",
  • "editable": true,
  • "email": "string",
  • "id": 0,
  • "name": "string",
  • "pending": true,
  • "surname": "string"
}

InviteOwner

Invite the passed owner to the organization

Request Body schema: application/json

owner invite payload

organizationID
integer <int64>
ownerID
integer <int64>

Responses

200

owner was successfully invited

400

owner invite payload is missing or in the wrong format

500

unexpected error

post /user/invite/owner
https://app.groupalarm.com/api/v1/user/invite/owner

Request samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "organizationID": 0,
  • "ownerID": 0
}

ResendInvitation

Resends the invitation email of an existing user to an organization

Request Body schema: application/json

invitation payload

createNewLabels
boolean

If set to true while importing a user with a label name but not an id, we will automatically create and assign this label. This setting will only work in conjunction with MapLabelsByName.

mapLabelsByName
boolean

If set to true while importing a user with a label name but not an id, we will try to find a label with this name and assign it.

organization
required
object (Organization)

Organization defines an organization payload

users
required
Array of objects (BulkUserElement)

array of user bulk elements

Responses

200

user was successfully invited

400

user invite payload is missing or in the wrong format

500

unexpected error

post /user/resend
https://app.groupalarm.com/api/v1/user/resend

Request samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "createNewLabels": true,
  • "mapLabelsByName": true,
  • "organization":
    {
    },
  • "users":
    [