User API specification (2.8.2)

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

Login

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

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-04-02T13:56:38Z",
  • "surname": "string",
  • "token": "string"
}

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

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-04-02T13:56:38Z",
  • "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

organization
required
object (Organization)

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
{
  • "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

organization
required
object (Organization)

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
{
  • "organization":
    {
    },
  • "users":
    [
    ]
}

GetSpecificUser

Returns a specific user with the passed api for organization members

path Parameters
userID
required
int64

ID of an user

query Parameters
organization
required
int64

ID of the organization

Responses

200

returns the requested user

500

unexpected error

get /user/{userID}