APIAuthentication

Authentication

Most API endpoints require authentication. Zipline supports cookie-based and token-based authentication

Cookie: zipline_session=Fe26.2*1*d5d6c1cab50913a978379ea0ecd59c3710aed83ca613bbf61c7c41b3277e7d37*Fzdkvvo4W7ISfMAX6oDBZg*jmTDus11i0148eJnE9_Ew6j15VD17SH9QdBMZ-zmubLJD_tuVSIdXPY6Rt2NvKS8_rsSaUsoQdEFd_mRTiokmPzVJtmUspKxpcQETrA9b0LGAH0o_PmjUWbTo3_NP6jv*1749608419139*66748d18c4a2af1224d936c9767c9985f9bb33682bbfcd8620ebe9f218a1f575*KSs0RJBnRM1LqTVt28UyHgXXODOMvu-h9zkId34lMtU~2

This is the default authentication method used by the dashboard. It uses a cookie named zipline_session to store the current session. This value is encrypted and signed to prevent tampering.

How to Request

Make a request to /api/auth/login with your username and password:

{
  "username": "your_username",
  "password": "your_password"
}

If successful, the response will include a Set-Cookie header with the zipline_session cookie:

zipline_session=Fe26.2*1*ee8c4def77971edd2ac2e080deb64593c9afde34f6174f56c0d2cbb01495a42c*xfgpt-lpg8y8ZAV_pbtwcw*NxdBaMzTeJcC6v_F2D5C_Ex0dZncB12PNb5XLXY-tjnZa09RKaEIo4RxuQ56MGWwMfMH-2QairlPuV4ogx40izqLPzoJwP7qRLMXxKkjO_Ntbw-rRVcIrq5qgcZ7Wgyu*1750023520306*548beb4fffae6af0ea9839d0cc45510c8ff30a3a96bc0192d9ee1f67531f5609*mH9HqYqf219qDWmRBfK6oNG-hxJeIY9WO6OwrnUAObs~2; Max-Age=604800; Path=/; Expires=Sun, 08 Jun 2025 21:24:59 GMT; SameSite=Lax

Include this cookie in any requests that require authentication by adding it to the Cookie header:

Cookie: zipline_session=Fe26.2*1*ee8c4def77971edd2ac2e080deb64593c9afde34f6174f56c0d2cbb01495a42c*xfgpt-lpg8y8ZAV_pbtwcw*NxdBaMzTeJcC6v_F2D5C_Ex0dZncB12PNb5XLXY-tjnZa09RKaEIo4RxuQ56MGWwMfMH-2QairlPuV4ogx40izqLPzoJwP7qRLMXxKkjO_Ntbw-rRVcIrq5qgcZ7Wgyu*1750023520306*548beb4fffae6af0ea9839d0cc45510c8ff30a3a96bc0192d9ee1f67531f5609*mH9HqYqf219qDWmRBfK6oNG-hxJeIY9WO6OwrnUAObs~2

Token Based

Authorization: MTc0ODgxMzk5MTI1Mw==.ZjM1YTRiOThkYTU2ZWY1MGRhYWY2OWVlZTA0ZDA4YjQuMGU3ZjlhNDJiOTdlZTZhY2UzNDNlMzQwYjc4ZmE5MTg2ZjVhZDM0NzMyYzE0MTZmYTFkMGU3Mzc3NTA0M2U1YTU0MTdkMjZkNWYxNjlkOWM2NmYyYTYzNDBkNDEzZDYyNWM5OWRhNzIwMzE3MWFmNjVlM2I0ZGNkOTc4YjIzYzE2NmZiOTM0YTgzN2Q0Y2VhNjU0MjFjMjI2ZTYyYTE5OQ==

This method uses a random, signed token that is generated whenever you request a token. This token is valid forever until it is reset in the dashboard or via the API.

Make any requests that require authentication by including the Authorization header with your token:

Authorization: token

Getting a Token with the Dashboard

Click your username in the top right corner

Click "Copy Token"
Follow the steps in the modal, and then it will copy your token to the clipboard.

Getting a Token with the API

This method is more complicated, as it requires you to first authenticate using the cookie method, then make a request to the /api/user/token endpoint to get your token.

Authenticate using the cookie method to get the zipline_session cookie.
Make a request to the /api/user/token endpoint:

GET /api/user/token

This will return a response like:

{
  "token": "MTc0ODgxMzk5MTI1Mw==.ZjM1YTRiOThkYTU2ZWY1MGRhYWY2OWVlZTA0ZDA4YjQuMGU3ZjlhNDJiOTdlZTZhY2UzNDNlMzQwYjc4ZmE5MTg2ZjVhZDM0NzMyYzE0MTZmYTFkMGU3Mzc3NTA0M2U1YTU0MTdkMjZkNWYxNjlkOWM2NmYyYTYzNDBkNDEzZDYyNWM5OWRhNzIwMzE3MWFmNjVlM2I0ZGNkOTc4YjIzYzE2NmZiOTM0YTgzN2Q0Y2VhNjU0MjFjMjI2ZTYyYTE5OQ=="
}

Use this token in the Authorization header for subsequent requests:

Authorization: MTc0ODgxMzk5MTI1Mw==.ZjM1YTRiOThkYTU2ZWY1MGRhYWY2OWVlZTA0ZDA4YjQuMGU3ZjlhNDJiOTdlZTZhY2UzNDNlMzQwYjc4ZmE5MTg2ZjVhZDM0NzMyYzE0MTZmYTFkMGU3Mzc3NTA0M2U1YTU0MTdkMjZkNWYxNjlkOWM2NmYyYTYzNDBkNDEzZDYyNWM5OWRhNzIwMzE3MWFmNjVlM2I0ZGNkOTc4YjIzYzE2NmZiOTM0YTgzN2Q0Y2VhNjU0MjFjMjI2ZTYyYTE5OQ==

Error Responses

If authentication fails, or is not present you will receive a 401 Unauthorized response, that looks like this:

❯ curl -v http://localhost:3000/api/user
* Connected to localhost (127.0.0.1) port 3000
> GET /api/user HTTP/1.1
> Host: localhost:3000
> User-Agent: curl/8.7.1
> Accept: */*
>
* Request completely sent off
< HTTP/1.1 401 Unauthorized
< access-control-allow-origin: *
< content-type: application/json; charset=utf-8
< content-length: 42
< Date: Sun, 01 Jun 2025 21:55:21 GMT
< Connection: keep-alive
< Keep-Alive: timeout=72
<
* Connection #0 to host localhost left intact
{"error":"not logged in","statusCode":401}

Resources

For more information on how tokens work in Zipline, refer to the /api/user/token endpoint documentation, where it is explained in detail.

User

The User object represents a Zipline user and their associated setting...

Errors

All errors are formatted as JSON objects with the following structure....

Last updated: 6/1/2025

Edit this page on GitHub