Users

Users, like most other web applications, are usually owned by a single person, and are used to categorize their activities and data. As Drop is intended to be a private platform, most requests need to be authenticated by a user first.

The user model

The user model contains most of the profile information about a user, including their username and profile picture. User endpoints should be used to fetch, interact and manage users, and update information about them.

Properties

Name
id
Type
string
Description
UUID of the user. Used internally to refer to this user.
Name
username
Type
string
Description
Unique alphanumeric username (with length limitations), used for character-restricted representations of users (like IGNs).
Name
displayName
Type
string
Description
Unconstrained preferred name of this user. Used when possible.
Name
email
Type
string
Description
Email of this user. Not currently used, but collected in case of future functionality.
Name
profilePictureObjectId
Type
string
Description
The object ID of this user's profile picture. Check out the Objects API on how to fetch the image.
Name
admin
Type
boolean
Description
Admin flag. If enabled, this user has access to system-level endpoints.
Name
enabled
Type
boolean
Description
If this user is currently enabled, and can be access.

GET/api/v1/userUSERACL: read

Fetch current user

This endpoint fetches the current user. If you are authenticated, it returns the user. If you are not, it returns null.

Request

GET

/api/v1/user

curl -G http://localhost:3000/api/v1/user \
  -H "Authorization: Bearer {token}"

Response

{
    "id": "d2b487be-f796-4259-83d9-6ec27ad2947e",
    "username": "exampleusername",
    "email": "example@example.com",
    "displayName": "Example Username",
    "profilePictureObjectId": "1d5f7aeb-df75-439c-a2e9-b875af4724d2",
    "admin": true,
    "enabled": true
}

GET/api/v1/admin/usersSYSTEMACL: user:read

List all users

This endpoint fetches all users on this instance.

Request

GET

/api/v1/admin/users

curl -G http://localhost:3000/api/v1/admin/users \
  -H "Authorization: Bearer {token}"

Response

[
    {
        "id": "d2b487be-f796-4259-83d9-6ec27ad2947e",
        "username": "exampleusername",
        "email": "example@example.com",
        "displayName": "Example Username",
        "profilePictureObjectId": "1d5f7aeb-df75-439c-a2e9-b875af4724d2",
        "admin": true,
        "enabled": true
    }
]

GET/api/v1/admin/users/:idSYSTEMACL: user:read

Fetch user

This endpoint fetches a user by ID.

Route parameters

Name
id
Type
string
Description
ID of user you want to fetch.

Request

GET

/api/v1/admin/users/:id

curl -G http://localhost:3000/api/v1/admin/users/{id} \
  -H "Authorization: Bearer {token}"

Response

{
    "id": "d2b487be-f796-4259-83d9-6ec27ad2947e",
    "username": "exampleusername",
    "email": "example@example.com",
    "displayName": "Example Username",
    "profilePictureObjectId": "1d5f7aeb-df75-439c-a2e9-b875af4724d2",
    "admin": true,
    "enabled": true
}

DELETE/api/v1/admin/users/:idSYSTEMACL: user:delete

Delete user

This endpoint deletes a user by ID

Route parameters

Name
id
Type
string
Description
ID of user you want to delete.

Request

DELETE

/api/v1/admin/users/:id

curl -X DELETE http://localhost:3000/api/v1/admin/users/{id} \
  -H "Authorization: Bearer {token}"

Response

No response returned.

Authentication mechanisms

With these endpoint above, you might be wondering, "well, how do you actually create a user?". That job, in Drop, is given to authentication mechanism. Each user can multiple, but at least one, authentication "mechanism" attached to their account. These may be (non-exhaustive):

Simple: username & password combination
OIDC: OpenID Connect, allowing for Single Sign On (SSO),

These authentication mechanisms are also responsible for creating the user, since each user must have at least one mechanism active.

GET/api/v1/admin/authSYSTEMACL: auth:read

Fetch authentication mechanisms

This endpoint returns all authentication mechanisms, and a configuration object for each if enabled, otherwise undefined. For mechanisms that require no authentication, the object is simply true or false depending on whether or not it's enabled.

Request

GET

/api/v1/admin/auth

curl -G http://localhost:3000/api/v1/admin/auth \
  -H "Authorization: Bearer {token}"

Response

{
    "Simple": true,
    "OpenID": {
        "authorizationUrl": "https://my.oidc.app/application/o/authorize/",
        "scopes": "openid, email, profile, offline_access",
        "adminGroup": "admin",
        "usernameClaim": "preferred_username",
        "externalUrl": "http://localhost:3000"
    }
}

Simple authentication

Simple authentication is the default and fallback in Drop. It relies on a simple username & password pair to log in. Users are created through a concept of invites.

GET/api/v1/admin/invitationSYSTEMACL: auth:simple:invitation:read

Fetch invitations

This endpoint is used to fetch all invitations for an instance.

Response

Name
id
Type
string
Description
Invitation ID, used as a secret for the invite.
Name
isAdmin
Type
boolean
Description
Whether or not this invite will create the user as an admin.
Name
username
Type
string
Description
Optional, will enforce a username on the account.
Name
email
Type
string
Description
Optional, will enforce an email on the account.
Name
expires
Type
timestamp
Description
Timestamp for when this invite will expire. If "Never" is selected in the UI, the invitation actually expires in 100 years.
Name
inviteUrl
Type
timestamp
Description
A link to the frontend page that will allow a user to register through a web browser. Uses the EXTERNAL_URL of the instance.

Request

GET

/api/v1/admin/invitation

curl -G http://localhost:3000/api/v1/admin/invitation \
  -H "Authorization: Bearer {token}"

Response

[
    {
        "id": "418d2c3f-8029-409e-b47c-0c3b158be3e1",
        "isAdmin": true,
        "username": "testusername",
        "email": "example@example.com",
        "expires": "2025-09-23T06:37:19.047Z",
        "inviteUrl": "http://localhost:3000/auth/register?id=418d2c3f-8029-409e-b47c-0c3b158be3e1"
    }
]

POST/api/v1/admin/invitationSYSTEMACL: auth:simple:invitation:new

Create invitation

This endpoint is used to create an invitation.

Required parameters

Name
expires
Type
timestamp
Description
Timestamp for when this invite will expire, in the format of an ISO timestamp. Typically, you can convert a JavaScript Date object.

Optional parameters

Name
username
Type
string
Description
Username to enforce on the invitation.
Name
email
Type
string
Description
Email to enforce on the invitation.
Name
isAdmin
Type
boolean
Description
Whether or not to make this an admin invitation, defaults to false.

Request

POST

/api/v1/admin/invitation

curl -X POST http://localhost:3000/api/v1/admin/invitation \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d "{ ... }"

Response

[
    {
        "id": "418d2c3f-8029-409e-b47c-0c3b158be3e1",
        "isAdmin": true,
        "username": "testusername",
        "email": "example@example.com",
        "expires": "2025-09-23T06:37:19.047Z",
        "inviteUrl": "http://localhost:3000/auth/register?id=418d2c3f-8029-409e-b47c-0c3b158be3e1"
    }
]

DELETE/api/v1/admin/invitationSYSTEMACL: auth:simple:invitation:delete

Delete an invitation

This endpoint is used to delete an invitation.

Required parameters

Name
id
Type
string
Description
ID of invitation to delete.

Request

DELETE

/api/v1/admin/invitation

curl -X DELETE http://localhost:3000/api/v1/admin/invitation \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d "{ ... }"

Response

No response.

GET/api/v1/auth/signup/simple

Fetch an invitation

This endpoint is used by un-authenticated clients to fetch details about an invitation. The invitation ID acts as a secret to access invitations.

Query parameters

Name
id
Type
string
Description
ID of invitation, fetched from the register URL.

Response properties

The response properties are the same as described in Fetch invitation.

Request

GET

/api/v1/auth/signup/simple

curl -G http://localhost:3000/api/v1/auth/signup/simple?id={id}

Response

{
  "id": "418d2c3f-8029-409e-b47c-0c3b158be3e1",
  "isAdmin": true,
  "username": "testusername",
  "email": "example@example.com",
  "expires": "2025-09-23T06:37:19.047Z"
}

POST/api/v1/auth/signup/simple

Create user

This endpoint consumes an invitation to create a user with the Simple authentication mechanism.

Request parameters

Name
invitation
Type
string
Description
ID of invitation, usually fetched from the register URL.
Name
password
Type
string
Description
Password of the user. Must be >= 14 characters.
Name
username
Type
string
Description
Username of the user. Must be set regardless if invitation will override it. Will be overriden if the invitation has it.
Name
email
Type
string
Description
Email of the user, uses basic email validation (x@y.z). Must be set regardless if invitation will override it. Will be overriden if the invitation has it.
Name
displayName
Type
string
Description
Optional, display name of user. No restrictions.

Request

POST

/api/v1/auth/signup/simple

curl -X POST http://localhost:3000/api/v1/auth/signup/simple?id={id} \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d "{ ... }"

Response

{
    "id": "d2b487be-f796-4259-83d9-6ec27ad2947e",
    "username": "exampleusername",
    "email": "example@example.com",
    "displayName": "Example Username",
    "profilePictureObjectId": "1d5f7aeb-df75-439c-a2e9-b875af4724d2",
    "admin": true,
    "enabled": true
}