The auth API makes it possible to register users, authorize users, manage users and more via a RESTful interface.
The base URL for production is https://auth-api.connectedcars.io
. Most requests requires an organization namespace header which can be found either in the first party clients or via your contact within Connected Cars.
An access token granted by this service is formatted as a JWT and normally have a lifetime of one hour while having the option of being exchanged for a new access token up to one hour after expiration. For system-to-system integrations or other setups with a requirement for automatic authorization, there is either the option of using a service account or a device token.
If nothing else is specified, the parameters listed are required.
Registers a user in the specified organization namespace.
POST /auth/register/email
Name | Type | In | Description |
---|---|---|---|
X-Organization-Namespace |
string | header | - |
email |
string | body | - |
password |
string | body | - |
curl \
-X POST \
-H "X-Organization-Namespace: organization:namespace" \
https://auth-api.connectedcars.io/auth/register/email \
-d '{"email":"email","password":"password"}'
Status: 200 OK
{
"token": "JWT",
"level": "AM1",
"expires": 3600
}
Registers a user via Apple in the specified organization namespace. This requires client credentials matching the server credentials for the organization namespace.
POST /auth/register/apple
Name | Type | In | Description |
---|---|---|---|
X-Organization-Namespace |
string | header | - |
token |
string | body | - |
curl \
-X POST \
-H "X-Organization-Namespace: organization:namespace" \
https://auth-api.connectedcars.io/auth/register/apple \
-d '{"token":"token"}'
Status: 200 OK
{
"token": "JWT",
"level": "AM1",
"expires": 3600
}
Registers a user via Azure AD in the specified organization namespace. This requires client credentials matching the server credentials for the organization namespace.
POST /auth/register/azure
Name | Type | In | Description |
---|---|---|---|
X-Organization-Namespace |
string | header | - |
token |
string | body | - |
curl \
-X POST \
-H "X-Organization-Namespace: organization:namespace" \
https://auth-api.connectedcars.io/auth/register/azure \
-d '{"token":"token"}'
Status: 200 OK
{
"token": "JWT",
"level": "AM1",
"expires": 3600
}
Registers a user via Facebook in the specified organization namespace. This requires client credentials matching the server credentials for the organization namespace.
POST /auth/register/facebook
Name | Type | In | Description |
---|---|---|---|
X-Organization-Namespace |
string | header | - |
token |
string | body | - |
curl \
-X POST \
-H "X-Organization-Namespace: organization:namespace" \
https://auth-api.connectedcars.io/auth/register/facebook \
-d '{"token":"token"}'
Status: 200 OK
{
"token": "JWT",
"level": "AM1",
"expires": 3600
}
Registers a user via Google in the specified organization namespace. This requires client credentials matching the server credentials for the organization namespace.
POST /auth/register/google
Name | Type | In | Description |
---|---|---|---|
X-Organization-Namespace |
string | header | - |
token |
string | body | - |
curl \
-X POST \
-H "X-Organization-Namespace: organization:namespace" \
https://auth-api.connectedcars.io/auth/register/google \
-d '{"token":"token"}'
Status: 200 OK
{
"token": "JWT",
"level": "AM1",
"expires": 3600
}
Registers a user via Volkswagen ID in the specified organization namespace. This requires client credentials matching the server credentials for the organization namespace.
POST /auth/register/we-id
Name | Type | In | Description |
---|---|---|---|
X-Organization-Namespace |
string | header | - |
token |
string | body | - |
curl \
-X POST \
-H "X-Organization-Namespace: organization:namespace" \
https://auth-api.connectedcars.io/auth/register/we-id \
-d '{"token":"token"}'
Status: 200 OK
{
"token": "JWT",
"level": "AM1",
"expires": 3600
}
Logs in a user in the specified organization namespace.
POST /auth/login/email/password
Name | Type | In | Description |
---|---|---|---|
X-Organization-Namespace |
string | header | - |
email |
string | body | - |
password |
string | body | - |
curl \
-X POST \
-H "X-Organization-Namespace: organization:namespace" \
https://auth-api.connectedcars.io/auth/login/email/password \
-d '{"email":"email","password":"password"}'
Status: 200 OK
{
"token": "JWT",
"level": "AM1",
"expires": 3600
}
Logs in a user via Apple in the specified organization namespace. This requires client credentials matching the server credentials for the organization namespace.
POST /auth/login/apple
Name | Type | In | Description |
---|---|---|---|
X-Organization-Namespace |
string | header | - |
token |
string | body | - |
curl \
-X POST \
-H "X-Organization-Namespace: organization:namespace" \
https://auth-api.connectedcars.io/auth/login/apple \
-d '{"token":"token"}'
Status: 200 OK
{
"token": "JWT",
"level": "AM1",
"expires": 3600
}
Logs in a user via Azure AD in the specified organization namespace. This requires client credentials matching the server credentials for the organization namespace.
POST /auth/login/azure
Name | Type | In | Description |
---|---|---|---|
X-Organization-Namespace |
string | header | - |
token |
string | body | - |
curl \
-X POST \
-H "X-Organization-Namespace: organization:namespace" \
https://auth-api.connectedcars.io/auth/login/azure \
-d '{"token":"token"}'
Status: 200 OK
{
"token": "JWT",
"level": "AM1",
"expires": 3600
}
Logs in a user via Facebook in the specified organization namespace. This requires client credentials matching the server credentials for the organization namespace.
POST /auth/login/facebookConverter
Name | Type | In | Description |
---|---|---|---|
X-Organization-Namespace |
string | header | - |
token |
string | body | - |
curl \
-X POST \
-H "X-Organization-Namespace: organization:namespace" \
https://auth-api.connectedcars.io/auth/login/facebookConverter \
-d '{"token":"token"}'
Status: 200 OK
{
"token": "JWT",
"level": "AM1",
"expires": 3600
}
Logs in a user via Google in the specified organization namespace. This requires client credentials matching the server credentials for the organization namespace.
POST /auth/login/googleConverter
Name | Type | In | Description |
---|---|---|---|
X-Organization-Namespace |
string | header | - |
token |
string | body | - |
curl \
-X POST \
-H "X-Organization-Namespace: organization:namespace" \
https://auth-api.connectedcars.io/auth/login/googleConverter \
-d '{"token":"token"}'
Status: 200 OK
{
"token": "JWT",
"level": "AM1",
"expires": 3600
}
Logs in a user via Volkswagen ID in the specified organization namespace. This requires client credentials matching the server credentials for the organization namespace.
POST /auth/login/we-id
Name | Type | In | Description |
---|---|---|---|
X-Organization-Namespace |
string | header | - |
token |
string | body | - |
curl \
-X POST \
-H "X-Organization-Namespace: organization:namespace" \
https://auth-api.connectedcars.io/auth/login/we-id \
-d '{"token":"token"}'
Status: 200 OK
{
"token": "JWT",
"level": "AM1",
"expires": 3600
}
Returns a new access token authorized by a previous access token expired at most one hour ago.
GET /auth/tokenRefresh
Name | Type | In | Description |
---|---|---|---|
X-Organization-Namespace |
string | header | - |
Authorization |
string | header | Use format Bearer TOKEN . |
curl \
-X GET \
-H "X-Organization-Namespace: organization:namespace" \
-H "Authorization: Bearer TOKEN" \
https://auth-api.connectedcars.io/auth/tokenRefresh
Status: 200 OK
{
"token": "JWT",
"level": "AM1",
"expires": 3600
}
Revokes an active access token. Can revoke tokens that have expired at most one hour ago.
GET /auth/logoutToken
Name | Type | In | Description |
---|---|---|---|
X-Organization-Namespace |
string | header | - |
Authorization |
string | header | Use format Bearer TOKEN . |
curl \
-X GET \
-H "X-Organization-Namespace: organization:namespace" \
-H "Authorization: Bearer TOKEN" \
https://auth-api.connectedcars.io/auth/logoutToken
Status: 200 OK
{
"status": "ok"
}
Initiates a password recovery flow which will send an email to the user with a link to set a new password.
POST /auth/recover/password/init
Name | Type | In | Description |
---|---|---|---|
X-Organization-Namespace |
string | header | - |
email |
string | body | - |
state |
string | body | - |
redirectUrl |
string | body | - |
curl \
-X POST \
-H "X-Organization-Namespace: organization:namespace" \
https://auth-api.connectedcars.io/auth/recover/password/init \
-d '{"email":"email","state":"state","redirectUrl":"redirectUrl"}'
Status: 200 OK
{
"status": "ok"
}
Completes a password recovery flow by setting a new password.
POST /recover/password/change
Name | Type | In | Description |
---|---|---|---|
X-Organization-Namespace |
string | header | - |
newPassword |
string | body | - |
token |
string | body | - |
curl \
-X POST \
-H "X-Organization-Namespace: organization:namespace" \
https://auth-api.connectedcars.io/auth/recover/password/change \
-d '{"newPassword":"newPassword","token":"token"}'
Status: 200 OK
{
"token": "JWT",
"level": "AM1",
"expires": 3600,
"state": "{\"some\":\"value\"}",
"redirectUrl": "https://app.minvolkswagen.dk/login"
}
Returns information about the logged in user.
GET /user/info
Name | Type | In | Description |
---|---|---|---|
X-Organization-Namespace |
string | header | - |
Authorization |
string | header | Use format Bearer TOKEN . |
curl \
-X GET \
-H "X-Organization-Namespace: organization:namespace" \
-H "Authorization: Bearer TOKEN" \
https://auth-api.connectedcars.io/user/info
Status: 200 OK
{
"id": 1,
"email": "[email protected]",
"mobile": "+4512345678",
"facebookId": null,
"hasDeprecatedFb": false,
"googleId": null,
"firstname": "John",
"lastname": "Doe",
"lang": "en"
}
Updates information on the logged in user. This should primarily be used for changing the password. Other operations can be performed via the GraphQL API.
PATCH /user/update
Name | Type | In | Description |
---|---|---|---|
X-Organization-Namespace |
string | header | - |
Authorization |
string | header | Use format Bearer TOKEN . |
firstname |
string | body | Optional. |
lastname |
string | body | Optional. |
email |
string | body | Optional. |
mobile |
string | body | Optional. |
lang |
string | body | Optional. |
password |
string | body | Optional. |
oldPassword |
string | body | Must be supplied along with password . Otherwise ignored. |
curl \
-X PATCH \
-H "X-Organization-Namespace: organization:namespace" \
-H "Authorization: Bearer TOKEN" \
https://auth-api.connectedcars.io/user/update \
-d '{"firstname":"firstname","lastname":"lastname","email":"email","mobile":"mobile","lang":"lang","password":"password","oldPassword":"oldPassword"}'
Status: 200 OK
{}
Links logged in user to Apple.
POST /user/link/apple
Name | Type | In | Description |
---|---|---|---|
X-Organization-Namespace |
string | header | - |
Authorization |
string | header | Use format Bearer TOKEN . |
token |
string | body | - |
curl \
-X POST \
-H "X-Organization-Namespace: organization:namespace" \
-H "Authorization: Bearer TOKEN" \
https://auth-api.connectedcars.io/user/link/apple
Status: 200 OK
{
"token": "token"
}
Unlinks logged in user from Apple.
POST /user/unlink/apple
Name | Type | In | Description |
---|---|---|---|
X-Organization-Namespace |
string | header | - |
Authorization |
string | header | Use format Bearer TOKEN . |
curl \
-X POST \
-H "X-Organization-Namespace: organization:namespace" \
-H "Authorization: Bearer TOKEN" \
https://auth-api.connectedcars.io/user/unlink/apple
Status: 200 OK
{}
Links logged in user to Azure AD.
POST /user/link/azure
Name | Type | In | Description |
---|---|---|---|
X-Organization-Namespace |
string | header | - |
Authorization |
string | header | Use format Bearer TOKEN . |
token |
string | body | - |
curl \
-X POST \
-H "X-Organization-Namespace: organization:namespace" \
-H "Authorization: Bearer TOKEN" \
https://auth-api.connectedcars.io/user/link/azure
Status: 200 OK
{
"token": "token"
}
Unlinks logged in user from Azure AD.
POST /user/unlink/azure
Name | Type | In | Description |
---|---|---|---|
X-Organization-Namespace |
string | header | - |
Authorization |
string | header | Use format Bearer TOKEN . |
curl \
-X POST \
-H "X-Organization-Namespace: organization:namespace" \
-H "Authorization: Bearer TOKEN" \
https://auth-api.connectedcars.io/user/unlink/azure
Status: 200 OK
{}
Links logged in user to Facebook.
POST /user/link/facebook
Name | Type | In | Description |
---|---|---|---|
X-Organization-Namespace |
string | header | - |
Authorization |
string | header | Use format Bearer TOKEN . |
token |
string | body | - |
curl \
-X POST \
-H "X-Organization-Namespace: organization:namespace" \
-H "Authorization: Bearer TOKEN" \
https://auth-api.connectedcars.io/user/link/facebook
Status: 200 OK
{
"token": "token"
}
Unlinks logged in user from Facebook.
POST /user/unlink/facebook
Name | Type | In | Description |
---|---|---|---|
X-Organization-Namespace |
string | header | - |
Authorization |
string | header | Use format Bearer TOKEN . |
curl \
-X POST \
-H "X-Organization-Namespace: organization:namespace" \
-H "Authorization: Bearer TOKEN" \
https://auth-api.connectedcars.io/user/unlink/facebook
Status: 200 OK
{}
Links logged in user to Google.
POST /user/link/google
Name | Type | In | Description |
---|---|---|---|
X-Organization-Namespace |
string | header | - |
Authorization |
string | header | Use format Bearer TOKEN . |
token |
string | body | - |
curl \
-X POST \
-H "X-Organization-Namespace: organization:namespace" \
-H "Authorization: Bearer TOKEN" \
https://auth-api.connectedcars.io/user/link/google
Status: 200 OK
{
"token": "token"
}
Unlinks logged in user from Google.
POST /user/unlink/google
Name | Type | In | Description |
---|---|---|---|
X-Organization-Namespace |
string | header | - |
Authorization |
string | header | Use format Bearer TOKEN . |
curl \
-X POST \
-H "X-Organization-Namespace: organization:namespace" \
-H "Authorization: Bearer TOKEN" \
https://auth-api.connectedcars.io/user/unlink/google
Status: 200 OK
{}
Links logged in user to Volkswagen ID.
POST /user/link/we-id
Name | Type | In | Description |
---|---|---|---|
X-Organization-Namespace |
string | header | - |
Authorization |
string | header | Use format Bearer TOKEN . |
token |
string | body | - |
curl \
-X POST \
-H "X-Organization-Namespace: organization:namespace" \
-H "Authorization: Bearer TOKEN" \
https://auth-api.connectedcars.io/user/link/we-id
Status: 200 OK
{
"token": "token"
}
Unlinks logged in user from Volkswagen ID.
POST /user/unlink/we-id
Name | Type | In | Description |
---|---|---|---|
X-Organization-Namespace |
string | header | - |
Authorization |
string | header | Use format Bearer TOKEN . |
curl \
-X POST \
-H "X-Organization-Namespace: organization:namespace" \
-H "Authorization: Bearer TOKEN" \
https://auth-api.connectedcars.io/user/unlink/we-id
Status: 200 OK
{}
Returns the devices registered for the logged in user. The deviceToken
returned in the response only contains the first identifying part of the actual token used for authorizing the device.
GET /user/devices
Name | Type | In | Description |
---|---|---|---|
X-Organization-Namespace |
string | header | - |
Authorization |
string | header | Use format Bearer TOKEN . |
curl \
-X GET \
-H "X-Organization-Namespace: organization:namespace" \
-H "Authorization: Bearer TOKEN" \
https://auth-api.connectedcars.io/user/devices
Status: 200 OK
[
{
"deviceModel": "iPhone 11 Pro",
"deviceName": "John's iPhone",
"deviceToken": "deviceTokenWithoutKeyPart",
"lastLogin": "2021-08-06T12:00:00.000Z"
}
]
Registers a device for the logged in user.
POST /user/registerDevice
Name | Type | In | Description |
---|---|---|---|
X-Organization-Namespace |
string | header | - |
Authorization |
string | header | Use format Bearer TOKEN . |
deviceName |
string | body | Optional but recommended. |
deviceModel |
string | body | Optional but recommended. |
curl \
-X POST \
-H "X-Organization-Namespace: organization:namespace" \
https://auth-api.connectedcars.io/user/registerDevice \
-d '{"deviceName":"deviceName","deviceModel":"deviceModel"}'
Status: 200 OK
{
"deviceModel": "iPhone 11 Pro",
"deviceName": "John's iPhone",
"deviceToken": "deviceToken"
}
Logs in a user via a device token in the specified organization namespace. The device token can be obtained by registering a device.
POST /auth/login/deviceToken
Name | Type | In | Description |
---|---|---|---|
X-Organization-Namespace |
string | header | - |
deviceToken |
string | body | - |
curl \
-X POST \
-H "X-Organization-Namespace: organization:namespace" \
https://auth-api.connectedcars.io/auth/login/deviceToken \
-d '{"deviceToken":"deviceToken"}'
Status: 200 OK
{
"token": "JWT",
"level": "AM1",
"expires": 3600
}
Deletes a device registered to the logged in user.
POST /user/deleteDevice
Name | Type | In | Description |
---|---|---|---|
X-Organization-Namespace |
string | header | - |
Authorization |
string | header | Use format Bearer TOKEN . |
deviceExternalId |
string | body | The deviceToken field from the GET /user/devices response. |
curl \
-X POST \
-H "X-Organization-Namespace: organization:namespace" \
https://auth-api.connectedcars.io/user/deleteDevice \
-d '{"deviceExternalId":"deviceExternalId"}'
Status: 200 OK
{}
Creates a signed jwt token confirming that the user calling this endpoint is fleet owner of the supplied fleet ids
POST /user/signFleetIds
Name | Type | In | Description |
---|---|---|---|
X-Organization-Namespace |
string | header | - |
Content-Type |
string | header | should be application/json |
fleetIds |
number[] | body | The fleetIds that the user is owner of and should be in the returned token |
curl \
-X POST \
-H "Content-Type: application/json" \
-H "X-Organization-Namespace: organization:namespace" \
-H "Authorization: Bearer TOKEN" \
https://auth-api.connectedcars.io/user/signFleetIds \
-d '{"fleetIds":[1,2,3]}'
Status: 200 OK
{
"token": "JWT",
"expires": 3600
}
Logs in a service account in the specified organization namespace. This requires a service account set up by Connected Cars, for reference see example in Java or example in Node.js.
POST /auth/login/serviceAccountConverter
Name | Type | In | Description |
---|---|---|---|
X-Organization-Namespace |
string | header | - |
token |
string | body | - |
curl \
-X POST \
-H "X-Organization-Namespace: organization:namespace" \
https://auth-api.connectedcars.io/auth/login/serviceAccountConverter \
-d '{"token":"token"}'
Status: 200 OK
{
"token": "JWT",
"level": "AM1",
"expires": 3600
}
Returns a list of valid public keys.
GET /certs
curl \
-X GET \
https://auth-api.connectedcars.io/certs
Status: 200 OK
{
"keys": [
{
"kid": "2",
"alg": "RS256",
"use": "sig",
"kty": "RSA",
"n": "o_Xh5DmJJRn20zk-1i2YBxlTrILn3-S9_bt48c1DzGwNrRZaU3l2g_qZs3ui78nU_12J8i7aqWbKK9l9QbSLSspYQSEMWJvur8hb1xHPH9w7uV9MfkScDtvQKoiotaeay6DBZ5FkZTEazsiYLrhMFoI9zD0IrvJ5hROQ3TdMJu5Gse9VKq5DV0TjAomlebKlRPN4PSIBbcBSasH9l7Fli1MU0csyWj69-4UdM0SVwT3aOGlYinHLHlxNVOrEhIDroPN6hzNjSL5hq3Ssa6yVdeTyC0drEGwqjGQmG5KaZCLLbTW7OVinfsY6xFvPfYl_PjMbsUIumvwRgHyFZyzTZQ",
"e": "AQAB"}
]
}
Returns the list of all available revoked tokens
GET /auth/revokedTokens
curl \
-X GET \
https://auth-api.connectedcars.io/auth/revokedTokens
Status: 200 OK
{
"revokedTokens": [
{
"jti": "f2b85a99-4a3b-49e8-b616-af0cf68793e9",
"revokedAt": "2023-03-16 05:53:51.065"
}
]
}
Returns an object with valid public keys.
GET /pubKeys
curl \
-X GET \
https://auth-api.connectedcars.io/pubKeys
Status: 200 OK
{
"https://auth-api.connectedcars.io": {
"kty": "RSA",
"kid": "1",
"alg": "RS256",
"pem": "-----BEGIN PUBLIC KEY-----\npublicKey\n-----END PUBLIC KEY-----"
}
}
The type
field in the error responses can be expected to be stable while the message
field may change over time. Below are (non-exhaustive) examples of different status codes and errors you may encounter.
Status: 400 Bad Request
{
"message": "Password is too short",
"type": "password_too_short"
}
Status: 401 Unauthorized
{
"message": "JWT verification error",
"type": "jwt_verify_error"
}
Status: 403 Forbidden
{
"message": "User is archived",
"type": "user_archived"
}
Status: 404 Not Found
{
"message": "User not found",
"type": "user_not_found"
}
Status: 405 Method Not Allowed
{
"message": "Invalid CORS origin",
"type": "invalid_cors_origin"
}
Status: 409 Conflict
{
"message": "Email already exists",
"type": "email_exists"
}
Use the Retry-After
response header to determine the amount of seconds to wait before retrying.
Status: 429 Too Many Requests
{
"message": "Too many login attempts",
"type": "too_many_requests"
}
Status: 500 Internal Server Error
{
"message": "Internal server error",
"type": "internal_server_error"
}
You might get rate limited if you run too many requests against this API. If you hit the rate limit, you will get an error message with the status code 429. This response will include a Retry-After
header indicating how many seconds you at the least need to wait before making another request.