Auth

POST /api/auth/login

POST

CarAPI uses JSON Web Tokens (JWT) to authenticate requests. This endpoint generates a JWT token using your API Token (UUID) and API Secret (random 32 character string). Please login to your account and generate a token/secret if you have not already.

Note

Your email address and password cannot be used to generate a JWT. You must use your API token and secret.

If you don’t yet have API credentials, you must first register and then generate a secret. Users without a subscription will have limited data access.

Sample Request

cURL

curl -X POST https://carapi.app/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "api_token": "your_api_token_here",
    "api_secret": "your_api_secret_here"
  }'

NodeJS

const response = await fetch('https://carapi.app/api/auth/login', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    api_token: 'your_api_token_here',
    api_secret: 'your_api_secret_here'
  })
});

const jwt = await response.text();
console.log('JWT Token:', jwt);

Python

import requests

response = requests.post(
    'https://carapi.app/api/auth/login',
    json={
        'api_token': 'your_api_token_here',
        'api_secret': 'your_api_secret_here'
    }
)

jwt = response.text
print(f'JWT Token: {jwt}')

PHP (Guzzle)

use GuzzleHttp\Client;

$client = new Client();

$response = $client->post('https://carapi.app/api/auth/login', [
    'json' => [
        'api_token' => 'your_api_token_here',
        'api_secret' => 'your_api_secret_here',
    ],
]);

$jwt = (string) $response->getBody();
echo 'JWT Token: ' . $jwt;

PHP (cURL)

$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, 'https://carapi.app/api/auth/login');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, ['Content-Type: application/json']);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode([
    'api_token' => 'your_api_token_here',
    'api_secret' => 'your_api_secret_here',
]));

$jwt = curl_exec($ch);
curl_close($ch);

echo 'JWT Token: ' . $jwt;

Sample Response

eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJpc3MiOiJodHRwczovL2NhcmFwaS5hcHAiLCJzdWIiOiIxMjM0NSIsImV4cCI6MTY5ODc2NTQzMn0.example_token_signature

Using the JWT Token

Once you have your JWT token, include it in the Authorization header for all subsequent requests:

cURL

curl https://carapi.app/api/makes \
  -H "Authorization: Bearer YOUR_JWT_TOKEN_HERE"

NodeJS

const response = await fetch('https://carapi.app/api/makes', {
  headers: {
    'Authorization': `Bearer ${jwt}`
  }
});

Python

import requests

headers = {'Authorization': f'Bearer {jwt}'}
response = requests.get('https://carapi.app/api/makes', headers=headers)

PHP (Guzzle)

use GuzzleHttp\Client;

$client = new Client();

$response = $client->get('https://carapi.app/api/makes', [
    'headers' => [
        'Authorization' => 'Bearer YOUR_JWT_TOKEN_HERE',
    ],
]);

$data = json_decode($response->getBody(), true);
print_r($data);

PHP (cURL)

$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, 'https://carapi.app/api/makes');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'Authorization: Bearer YOUR_JWT_TOKEN_HERE',
]);

$response = curl_exec($ch);
curl_close($ch);

$data = json_decode($response, true);
print_r($data);

You can begin developing immediately with CarAPI without authentication, but to unlock all data you must subscribe and send a valid JSON Web Token (JWT) along with your request. To request a JWT you must first sign up and then generate an API Secret from your user dashboard.

Next send an HTTP POST request to /api/auth/login:

curl -X 'POST' \
  'https://carapi.app/api/auth/login' \
  -H 'accept: text/plain' \
  -H 'Content-Type: application/json' \
  -d '{
    "api_token": "your_api_token",
    "api_secret": "your_secret"
  }'

Now include the JWT in all your requests:

curl -X 'GET' \
  'https://carapi.app/api/models/v2' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer replace_this_with_your_jwt'

Remember to request a new JWT after paying for your subscription

If your JWT was created before you became a paying customer, you will need to regenerate a JWT. Only after creating a new JWT will it contain your new subscription status.

More on JWTs

Your JWT should be kept secure and confidential. It’s also important to cache your JWT so you don’t have to request a new one on each request (this is bad for performance). When re-using JWTs be sure to check the expiration and renew as needed.

Your JWT will be a very long base64 encoded string that contains three parts separated by periods: a header, payload, and signature.

Payload

The middle piece, the payload, is the only portion of the JWT you need to worry about when integrating with CarAPI. After the payload has been base64 decoded it becomes a standard JSON string that will look something like this:

{
  "iss": "carapi.app",
  "sub": "56e9c7cc-e1db-4f41-8b9a-e7857d750761",
  "aud": "56e9c7cc-e1db-4f41-8b9a-e7857d750761",
  "exp": 1698276870,
  "iat": 1697672070,
  "jti": "12cdc9c5-2c2c-4dda-a570-359608275213",
  "user": {
    "subscribed": true,
    "subscription": "starter",
    "rate_limit_type": "soft"
  }
}

The properties in the decoded payload are called “claims” per the JWT standard.

Registered Claims

You can expect registered claims in all JWT tokens regardless of who is providing them. Some of these claims such as expiration (exp) are required and important to understand while others are less important or not required.

• exp: (int) When this JWT will expire as a unix timestamp. If the current time in America/New_York (EST) is greater than this value your JWT will no longer work and the API will return a 401 error. This is 7 days from creation, but that value could change so it’s important that you validate your JWT is not expired before each request. If it is, you must generate a new one.
• iss: (string) This should always be "carapi.app", you don’t need to do anything with this.
• iat: (int) The time your JWT was created at as a unix timestamp. You don’t need to do anything with this.
• jti: (string) You don’t need to do anything with this.
• sub: (string) You don’t need to do anything with this.
• aud: (string) You don’t need to do anything with this.

Learn more about JWTs

jwt.io has a free JWT decoder and many resources on JWTs. You can read more about registered claims and the JWT spec in the official RFC.

Private Claims

These are application-specific properties added by API providers such as CarAPI.

• user.subscribed: (bool) Whether you have an active subscription.
• user.subscription: (string|null) The name of your subscription plan if any.
• user.rate_limit_type: (string) Whether you have hard rate limiting or soft rate limiting enabled.

Header and Signatures

The JWT has three total parts. You don’t need to worry about the other two. The first piece, the header, is metadata used to identify the hashing algorithm. The last piece, the signature, is used to verify the JWT was not tampered with. There are scenarios where these may be important to API clients, but it’s not something you need to worry about to securely and successfully integrate with CarAPI.

Best Practices

• Cache your JWT: Store the token and reuse it for multiple requests to avoid rate limiting on the auth endpoint (20 requests/minute max)
• Check expiration: Decode your JWT token to check the exp (expiration) claim and request a new token before it expires
• Secure storage: Never commit your API credentials to source control. Use environment variables or secure credential management

Learn more about JSON Web Tokens at https://jwt.io/.