Authentication and Authorization
myKaarma APIs support both Basic Authentication and OAuth2 for securing access to their resources. Clients must authenticate with valid credentials to make successful API requests.
Credential Acquisition
- Service Subscriber Creation: To obtain API access credentials, clients must please fill this form. Upon request, a dedicated
ServiceSubscriber
account will be created. - Credential Provision: The
ServiceSubscriber
account will be provisioned with either (or both):- A unique
username
andpassword
for Basic Authentication - A unique
client_id
andclient_secret
for OAuth2 These credentials will be securely provided to the client.
- A unique
Authentication Methods
Basic Authentication
Basic Authentication Header: Clients are required to include an
Authorization
header in every API request.Header Format: The
Authorization
header must use the Basic Authentication scheme. The format is as follows:Authorization: Basic <base64_encoded_credentials>
Credential Encoding:
- Concatenate the
username
andpassword
with a colon (:
) separator (e.g.,username:password
). - Encode the resulting string using Base64 encoding.
Example:
If your
username
isapiuser
and yourpassword
issecurepass
, the process would be:- Concatenate:
apiuser:securepass
- Base64 encode:
YXBpdXNlcjpzZWN1cmVwYXNz
- The
Authorization
header would be:Authorization: Basic YXBpdXNlcjpzZWN1cmVwYXNz
- Concatenate the
Request Inclusion: The client must include the constructed
Authorization
header in the header section of every API request.
Example API Request (using curl)
curl -X GET \
'https://api.mykaarma.com/resource' \
-H 'Authorization: Basic YXBpdXNlcjpzZWN1cmVwYXNz'
OAuth2 Authentication
OAuth2 implementation is currently in progress. Not all API resources are protected by OAuth2 authentication. Please contact myKaarma APIs Support to confirm which specific resources are available through OAuth2 authentication.
Given the sensitive nature of the data in myKaarma's platform, scopes are accessed at a granular level and are thoroughly reviewed before providing the credentials. Furthermore, the myKaarma administrator will have the chance to review all permissions you request. They will be able to deny access if they are not comfortable with the scope of requests.
Obtaining Access Token
To obtain an access token, make a POST request to the token endpoint:
curl --location 'https://api.mykaarma.com/authenticateAndAuthorize/oauth2/token' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'client_id=<CLIENT_ID>' \
--data-urlencode 'client_secret=<CLIENT_SECRET>' \
--data-urlencode 'grant_type=client_credentials'
Request Parameters
Parameter | Description | Required |
---|---|---|
client_id | Issued by myKaarma on creating the application | Yes |
client_secret | Issued by myKaarma on creating the application | Yes |
grant_type | Request type. Must be client_credentials | Yes |
Response
The response will consist of the following fields:
Success Response (200)
{
"access_token": "cD0G3qdqHRql70XGp8qkYOv6F6Sc0UCa",
"token_type": "bearer",
"expires_in": 7200
}
Error Responses
The following error codes are based on the OAuth 2.0 specification (RFC 6749):
- invalid_request
- invalid_client
- invalid_grant
- unauthorized_client
- unsupported_grant_type
Example error response (400):
{
"statusCode": 400,
"errors": [
{
"errorCode": "400",
"errorTitle": "invalid_request",
"errorMessage": "Invalid Request - {\"error_description\":\"Invalid client authentication\",\"error\":\"invalid_client\"}"
}
],
"warnings": []
}
{
"statusCode": 400,
"errors": [
{
"errorCode": "400",
"errorTitle": "unsupported_grant_type",
"errorMessage": "Unsupported Grant Type - grant_type needs to be in [\"client_credentials\"] "
}
],
"warnings": []
}
Using Access Token
OAuth2 Authentication Header: Clients are required to include an
Authorization
header in every API request.Header Format: The format is as follows:
Authorization: Bearer <generated_token>
Example API Request (using curl)
curl --location 'https://api.mykaarma.com/resource' \
--header 'Authorization: Bearer <ACCESS_TOKEN>'
Error Responses
Invalid/Expired Token (401)
{
"error_description": "The access token is invalid or has expired",
"error": "invalid_token"
}
Dealer/Department Authorization
In addition to authentication, each API endpoint requires either a dealerUuid
or departmentUuid
to validate authorization for specific entities. These identifiers are typically passed either in the URL as path variable, or as query parameters or within the request body, depending on the specific API endpoint.
Please contact your myKaarma API Representative to get these unique identifiers for the dealerships.
dealerUuid
: Used to authorize access for a specific dealer.departmentUuid
: Used to authorize access for a specific department.
Important Security Considerations
- Secure Storage: Clients are responsible for securely storing the provided credentials (username/password or client_id/client_secret). Avoid embedding credentials directly in client-side code.
- HTTPS Required: All API requests must be made over HTTPS to ensure the confidentiality of the transmitted credentials.
- Credential Rotation: Clients should periodically request new credentials to enhance security. Contact myKaarma APIs Support to initiate a credential rotation.
- Rate limiting: Excessive failed login attempts will result in temporary or permanent IP address blocking.
- Least Privilege: Service Subscribers will be granted only the minimum necessary permissions to perform their intended function.
Error Handling
- 401 Unauthorized: If the Authorization header is missing, invalid, or the provided credentials/token are incorrect, the API will return a 401 Unauthorized error.
- 403 Forbidden: If the supplied credentials/token are valid, but the client does not have permission to access the requested resource, a 403 Forbidden error will be returned.
Contact Information
For any questions or assistance with authentication and authorization, please send an email to myKaarma APIs Support.