Custom authentication

This page explains how to act on behalf of other users with logintokens and refreshtokens.

Use the endpoints described below when you need to execute API requests on behalf of other Filemail accounts. This can be useful when creating an app/UI that integrates with Filemail infrastructure, but requires other users to authenticate. Typical flow:

  1. Use the POST /auth/login providing user email and password.

  2. Store the resulting refreshtoken for later use in a secure place (it is valid for 3 months). The resulting logintoken (valid for 7 days) should be used to authenticate further requests.

  3. Include both x-api-key and logintoken in the request headers:

  4. x-api-key: mJE5v1zHs....
logintoken: r9BPAFW.....

  5. When you issue a request with an expired logintoken the server will return 401 HTTP status code. In that case use the refreshtoken and the POST /auth/refreshtoken endpoint to create a new logintoken. Note that the refreshtoken can be used only once. You will also get a new refreshtoken in the response every time you call POST /auth/refreshtoken.

post

Authenticate as a Filemail user. This operation generates a short-lived (7 days) logintoken and a long-lasting (3 months) refreshtoken. The refreshtoken can be later used to obtain a new logintoken.

Body
emailstring · min: 1Required

Email of the user.

passwordstring · min: 1Required

Password matching the user email.

Responses
200

OK

post
POST /auth/login HTTP/1.1
Host: api-public.filemail.com
Content-Type: application/json-patch+json
Accept: */*
Content-Length: 34

{
  "email": "text",
  "password": "text"
}
{
  "responsestatus": "OK",
  "errorid": "text",
  "errormessage": "text",
  "data": {
    "logintoken": "text",
    "logintokenExpireDate": 1,
    "refreshtoken": "text",
    "twoFactorToken": "text",
    "signInStatus": "NotAuthorized"
  },
  "errorcode": 1
}
post

Logout a Filemail user. This operation destroys the logintoken provided in the logintoken header and the associated refreshtoken.

Query parameters
allDevicesbooleanOptional

When set to true all the user's logintokens and refreshtokens will be destroyed.

Header parameters
logintokenstringOptional
Responses
200

OK

post
POST /auth/logout HTTP/1.1
Host: api-public.filemail.com
Accept: */*

{
  "responsestatus": "OK",
  "errorid": "text",
  "errormessage": "text",
  "data": null,
  "errorcode": 1
}
post

Generates new logintoken and a new refreshtoken based on an existing refreshtoken (obtained in the login operation). The provided refreshtoken will be destroyed.

Body
refreshtokenstringOptional

A one-time-use refreshtoken obtained from the login endpoint.

Responses
200

OK

post
POST /auth/refreshtoken HTTP/1.1
Host: api-public.filemail.com
Content-Type: application/json-patch+json
Accept: */*
Content-Length: 23

{
  "refreshtoken": "text"
}
{
  "responsestatus": "OK",
  "errorid": "text",
  "errormessage": "text",
  "data": {
    "logintoken": "text",
    "logintokenExpireDate": 1,
    "refreshtoken": "text"
  },
  "errorcode": 1
}
PreviousHandling contactsNextZapier

Last updated

Was this helpful?