Skip to main content

Authentication and Authorization

myKaarma API's utilizes Basic Authentication to secure access to its 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 a unique username and password. These credentials will be securely provided to the client.

Authentication Process​

  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'

Dealer/Department Authorization​

In addition to Basic 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 username and password. 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 are incorrect, the API will return a 401 Unauthorized error.
  • 403 Forbidden: If the supplied credentials are valid, but the user 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.

Future Authentication Strategy​

  • To enhance security and modernize our authentication protocols, we will be transitioning from basic authentication to OAuth 2.0 in the future.