Pixela Authentication: API Key Setup & Security (2026)

Authentication overview

Pixela provides a RESTful API designed for tracking and visualizing personal habits and metrics. Authentication for the Pixela API relies on a single, unique user token, referred to as the X-USER-TOKEN. This token is generated when a user creates their account and serves as the primary credential for all API interactions that require user-specific access, such as creating graphs, posting pixel data, or updating user profiles. The token must be securely transmitted with each API request in the HTTP header, ensuring that only authorized users can modify or retrieve their data.

The simplicity of Pixela's authentication model is consistent with its design philosophy as a personal, lightweight tracking service. While it doesn't employ complex multi-factor authentication (MFA) or OAuth flows, the reliance on a strong, secret user token necessitates careful handling to prevent unauthorized access. Developers integrating with Pixela should prioritize securing this token within their applications and environments to maintain data integrity and user privacy.

Supported authentication methods

Pixela primarily supports a single authentication method based on a user-specific API key. This key, designated as X-USER-TOKEN, is a long, randomly generated string that uniquely identifies a user account and authorizes API operations. The token functions similarly to a bearer token, where its mere presence in the request header grants access, making its confidentiality paramount.

No other authentication methods, such as OAuth 2.0 or Basic Authentication, are natively supported by the Pixela API for user-level access. The straightforward API key approach simplifies integration for developers focused on personal data tracking and visualization, as detailed in the official Pixela API reference.

Getting your credentials

To obtain your Pixela user token (X-USER-TOKEN), you must first create a user account. This process involves sending a POST request to the /v1/users endpoint with a chosen username and a secret token. The token you provide during user creation becomes your X-USER-TOKEN for all subsequent authenticated requests.

Here's a step-by-step guide to setting up your Pixela credentials:

1. Choose a Username: Select a unique username for your Pixela account. This will be part of your API endpoint paths.
2. Generate a User Token: Create a strong, secret string that will serve as your X-USER-TOKEN. This token should be complex and difficult to guess, similar to a secure password. The Pixela documentation on creating a user token recommends a length of 8 to 128 characters.
3. Create User Account: Send a POST request to the Pixela API to register your user. The request body should include your chosen username and the generated token. For example, using cURL:

curl -X POST https://pixe.la/v1/users \
  -H 'Content-Type: application/json' \
  -d '{"token":"your-chosen-secret-token","username":"your-username","agreeTermsOfService":"yes","notMinor":"yes"}'

Upon successful creation, the API will respond, and your your-chosen-secret-token is now your active X-USER-TOKEN. It is crucial to store this token securely, as Pixela does not provide a mechanism to retrieve it if lost. If the token is compromised or forgotten, you would need to create a new user account or update your existing user token, which requires knowing the current token.

Authenticated request example

Once you have your X-USER-TOKEN, you can include it in the HTTP header of your API requests. The token must be placed in the X-USER-TOKEN header field. This example demonstrates how to create a new graph using cURL, authenticated with the user token:

Example: Create a new graph

This request creates a graph named my-first-graph for tracking commits, with a unit of 'commit' and a color of 'shibafu'.

curl -X POST https://pixe.la/v1/users/your-username/graphs \
  -H 'X-USER-TOKEN: your-chosen-secret-token' \
  -H 'Content-Type: application/json' \
  -d '{
    "id": "my-first-graph",
    "name": "My First Graph",
    "unit": "commit",
    "type": "int",
    "color": "shibafu",
    "timezone": "Asia/Tokyo",
    "selfSufficient": "increment"
  }'

Replace your-username with your actual Pixela username and your-chosen-secret-token with your active X-USER-TOKEN. The X-USER-TOKEN header is essential for the API to identify and authorize the request against your account. Without this header, or with an invalid token, the API will return an authentication error.

Security best practices

Securing your Pixela X-USER-TOKEN is critical to prevent unauthorized access to your personal data and graphs. Adhering to fundamental API key security practices is essential, even for a personal tracking service.

1. Keep Your Token Secret: Treat your X-USER-TOKEN like a password. Never hardcode it directly into client-side code (e.g., JavaScript running in a browser) or expose it in public repositories.
2. Use Environment Variables: For server-side applications, store your token in environment variables rather than directly in your codebase. This prevents the token from being committed to version control systems. Many cloud platforms, like Google Cloud's API key best practices, recommend this approach.
3. Secure Storage: If your application requires persistent storage of the token, use secure storage mechanisms, such as encrypted vaults or secret management services. Avoid storing tokens in plain text files or databases.
4. Transmit Over HTTPS Only: Always ensure that all communications with the Pixela API occur over HTTPS. This encrypts the data in transit, protecting your X-USER-TOKEN from eavesdropping by malicious actors. Pixela's API endpoints are exclusively served over HTTPS, but it's important for client applications to enforce this.
5. Avoid Public Logs: Configure your application and server logs to redact or avoid logging API tokens. Accidental exposure in logs can lead to compromise.
6. Token Rotation: While Pixela doesn't enforce automatic token rotation, consider periodically updating your X-USER-TOKEN, especially if you suspect it might have been exposed. You can update your token via the Pixela API update user endpoint.
7. Least Privilege: Although Pixela's authentication model doesn't offer granular permissions, apply the principle of least privilege in your application design. Only allow your application to perform actions strictly necessary for its function.
8. Client-Side Considerations: For purely client-side applications, direct API key exposure is often unavoidable. In such cases, consider proxying requests through a backend server to add the X-USER-TOKEN, or accept the inherent risks for personal, low-stakes applications.