What we need

[] API Token

Follow these steps to create a Linear API token with read access for REST API calls:

1. Log in to your Linear account

   • Visit the Linear website and sign in with your credentials.
   • Make sure you have the necessary permissions to create API tokens.

2. Access your settings

   • Click on your profile picture in the bottom-left corner.
   • Select Settings from the dropdown menu.

3. Create a personal API token

   • In the left sidebar, click on API.
   • Click on + New token to create a new personal API token.
   • Enter a descriptive name for your token (e.g., “Read-only Access”).
   • Select the appropriate permissions for your token. For read-only access, select only the “Read” permissions you need.

   

4. Copy and secure your token

   • Once generated, copy the token value.
   • Store it securely. This token cannot be viewed again after you close the dialog.

5. Use the token with Bearer Authentication

   • The token is used with Bearer Authentication in the following format:
   • Include it in your API requests as an Authorization header:

Authorization: Bearer YOUR_LINEAR_API_TOKEN

You can use this token with the following Python function:

def linear_authentication_header(token=None):
    return {
        "Authorization": f"Bearer {token or os.environ['LINEAR_API_TOKEN']}"
    }

Permissions

The API token grants access based on the permissions you selected when creating it. Common API endpoints include:

• /api/issues — Get information about issues
• /api/teams — Get information about teams
• /api/users — Get information about users

Item Checklist of what’s needed for integration

1. Linear API token with appropriate permissions
2. Linear workspace URL (e.g., your-workspace.linear.app)

Required Permissions

To use the Linear API effectively, your token should have the appropriate permissions based on your needs:

• For read-only access: Select only the “Read” permissions for the resources you need to access
• For write access: Select both “Read” and “Write” permissions for the resources you need to modify
• For admin operations: Select the “Admin” permissions (use with caution)

Rate Limits

Linear API has rate limits in place. If you exceed these limits, you’ll receive a 429 Too Many Requests response. Implement appropriate retry logic with exponential backoff in your integration to handle rate limiting gracefully.