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

application/json-patch+jsonapplication/jsontext/jsonapplication/*+json

emailstring · min: 1Required

Email of the user.

passwordstring · min: 1Required

Password matching the user email.

Responses

200

OK

text/plainapplication/jsontext/json

400

Bad Request

text/plainapplication/jsontext/json

401

Unauthorized

text/plainapplication/jsontext/json

429

Too Many Requests

text/plainapplication/jsontext/json

post

/auth/login

HTTPcURLJavaScriptPython

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"
}

application/json-patch+jsonapplication/jsontext/jsonapplication/*+json

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

text/plainapplication/jsontext/json

401

Unauthorized

text/plainapplication/jsontext/json

post

/auth/logout

HTTPcURLJavaScriptPython

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

application/json-patch+jsonapplication/jsontext/jsonapplication/*+json

refreshtokenstringOptional

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

Responses

200

OK

text/plainapplication/jsontext/json

400

Bad Request

text/plainapplication/jsontext/json

post

/auth/refreshtoken

HTTPcURLJavaScriptPython

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

{
  "refreshtoken": "text"
}

application/json-patch+jsonapplication/jsontext/jsonapplication/*+json

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