API Personal Access Tokens
API Personal Access Tokens allow you to authenticate with the TeamGantt API using a secure token instead of your username and password. This is useful for integrating with third-party applications, building custom tools, or automating tasks.
What is a Personal Access Token?
Personal Access Tokens (PATs) are long-lived authentication credentials that provide access to your TeamGantt account. Each token is associated with your user account and can be used to make API requests on your behalf.
How to create a token?
To create a token, you must have the following requirements:
- You must be logged into your TeamGantt account.
- The token name is required and must be a string.
- Choose a descriptive name to help you identify the token's purpose later.
Once you have the above requirements, you can complete the steps to create a token.
- Navigate to the Account Settings page.
- Select API Personal Access Tokens.
- Then, enter a descriptive name for your token (e.g., "Mobile App Integration", "Automation Script").
- Click Create Token.
NOTE: Copy and save your token immediately - it will only be shown once!
Example:
```json { "token_name": "My Integration Token" } ``` **Response:** ```json { "token": "1|abc123def456ghi789jkl012mno345pqr678stu901vwx234yz" } ```<br>
How to use your token?
To use your token, include your token in the `Authorization` header of your API requests:
```text Authorization: Bearer 1|abc123def456ghi789jkl012mno345pqr678stu901vwx234yz ```
Example Request:
```bash curl -X GET "https://api.teamgantt.com/v1/current_user" \ -H "Authorization: Bearer YOUR_TOKEN_HERE" \ -H "Content-Type: application/json" ```
Managing Your Tokens
How to view all tokens?
You can see a list of all your active tokens in the API personal access tokens section of your account settings. Each token shows:
- Name: The descriptive name you gave it.
- Created: When the token was created.
- Last Used: When the token was last used (if applicable).
How to delete individual tokens?
To revoke access for a specific token, complete the following steps:
- Find the token in your list.
- Click the Delete icon next to the token.
- Confirm the deletion.
How to delete all tokens?
To revoke access for all your tokens at once, complete the following steps:
- Go to Account Settings > API Personal Access Tokens.
- Click Delete All Tokens.
- Confirm the action.
Security Best Practices
How to keep tokens secure?
- Keep tokens secret - Treat your tokens like passwords.
- Store your tokens securely - Save your tokens in a secure password manager or encrypted storage.
- Use HTTPS - Always make API requests over HTTPS.
- Rotate your tokens regularly - Consider creating new tokens periodically and deleting old ones.
How to name tokens?
When naming tokens, use descriptive terms that help you identify the purpose. Below are some good and bad examples:
- ✅ "Mobile App v2.1"
- ✅ "Automation Script - Project Updates"
- ✅ "Integration with Slack"
- ❌ "token1"
- ❌ "test"
When should I delete a token?
You should delete a token for the following reasons:
- No longer need the integration.
- Suspect a token has been compromised.
- Switching to a new token for the same purpose.
- To limit access to your account.
Troubleshooting
What are some common issues that may happen with a personal access token?
- "Token name is required."
- Make sure you've entered a name for your token before creating it.
- "Token name must be a string."
- Ensure the token name is text, not a number or other data type.
- "Unauthorized" error
- Check that your token is correct and hasn't been deleted.
- Verify you're using the `Bearer` prefix in the Authorization header.
- Ensure the token hasn't expired (tokens don't expire by default).
- Token not working
- Try creating a new token.
- Check that you copied the entire token correctly.
- Verify you're using the correct API endpoint.
How do I get help with my API access tokens?
If you're having trouble with API access tokens:
- Check that you're using the correct authentication method.
- Verify your token is still active in your account settings.
- Try creating a new token if the current one isn't working.
- Contact support if you continue to have issues.
What API endpoints are available?
The following endpoints are available for managing your tokens:
- `POST /v1/current_user/tokens/create` - Create a new token
- `GET /v1/current_user/tokens` - List all your tokens
- `DELETE /v1/current_user/tokens/{tokenId}` - Delete a specific token
- `DELETE /v1/current_user/tokens/delete` - Delete all tokens