Skip to main content

Authentication

Get a token from the API​

To make most of the requests to our API, you need to be authentified, you can authentify by making a request to obtain a token you will use after.

$ curl -X POST https://api-<instance>.toucantoco.com/login\
-H 'content-type: application/json'\
--data-binary '{"username": <username>, "password": <secret_password>}'
> {"token": <token>}
  • <instance> corresponds to your Toucan tenant,
  • <login> corresponds to your Toucan login,
  • <password> to your Toucan password and
  • <version> to the API version you want to use.
  • <token> is the token you will get afterward to authentify through this API.

Failed login limit​

Authenticating with invalid credentials will return Login failed. Invalid username or password:

$ curl https://api-<instance>.toucantoco.com/login\
-H 'content-type: application/json'\
--data-binary '{"username": <username>, "password": <secret_password>}'
> Login failed. Invalid username or password

After detecting several requests with invalid credentials within a short period (5 per minute), the API will temporarily reject all authentitication attemps for that user (including ones with valid credentials) with Too many requests in a short time, please wait a bit and try again.:

$ curl https://api-:instance.toucantoco.com/login\
-H 'content-type: application/json'\
--data-binary '{"username": <username>, "password": <secret_password>}'
>{"message":"Too many requests in a short time, please wait a bit and try again."}

Permissions​

If you do not have access to a resource. You will have a 401 return.

$ curl https://api-<instance>.toucantoco.com/v0/users
> {"statusCode":401,"message":"Unauthorized"}

Now you know how to properly authenticate! For most of the routes you also need to have a minimal user role, check here if you are interested.