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

1. Service Subscriber Creation: To obtain API access credentials, clients must please fill this form. Upon request, a dedicated ServiceSubscriber account will be created.
2. Credential Provision: The ServiceSubscriber account will be provisioned with either (or both):
   • A unique username and password for Basic Authentication
   • A unique client_id and client_secret for OAuth2 These credentials will be securely provided to the client.

Authentication Methods

Basic Authentication

1. Basic Authentication Header: Clients are required to include an Authorization header in every API request.

2. Header Format: The Authorization header must use the Basic Authentication scheme. The format is as follows:

   Authorization: Basic <base64_encoded_credentials>

3. Credential Encoding:

   • Concatenate the username and password with a colon (:) separator (e.g., username:password).
   • Encode the resulting string using Base64 encoding.

   Example:

   If your username is apiuser and your password is securepass, the process would be:

   1. Concatenate: apiuser:securepass
   2. Base64 encode: YXBpdXNlcjpzZWN1cmVwYXNz
   3. The Authorization header would be: Authorization: Basic YXBpdXNlcjpzZWN1cmVwYXNz

4. 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

caution

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

1. OAuth2 Authentication Header: Clients are required to include an Authorization header in every API request.

2. 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.