Kotini - Partner API (0.0.3)

Welcome to the Kotini Partners API documentation!

This API is designed to provide seamless integration with the Kotini platform, allowing our partners to access and manage data related to Case, Customer and Property.

This API follows RESTful principles and utilizes JSON for all request and response payloads, making it easy to integrate into your existing systems. It uses secure OAuth 2.0 authentication to ensure data integrity and privacy.

The documentation will guide you through all aspects of the Kotini Partners API, including authentication, request structures, endpoints, and best practices. Whether you're building an app or integrating Kotini data into your platform, this API will provide the tools you need for smooth operations.

This API uses OAuth 2.0 for authentication, supporting two flows:

1. Direct Access Grants (Resource Owner Password Credentials)
2. Standard Authorization Code Flow

Both methods provide secure access to the Partner API. The choice between them depends on your specific use case and security requirements.

Common Endpoints

Test Environment

• Token URL: https://auth.kotini.co/realms/partner/protocol/openid-connect/token
• Authorization URL: https://auth.kotini.co/realms/partner/protocol/openid-connect/auth

Production Environment

• Token URL: https://auth.kotini.co.uk/realms/partner/protocol/openid-connect/token
• Authorization URL: https://auth.kotini.co.uk/realms/partner/protocol/openid-connect/auth

This method is suitable for trusted applications that can securely handle user credentials.

Authentication Steps

1. Request Access Token: Send a POST request to the token URL with the required parameters.
2. Receive Access Token: Upon successful authentication, you'll receive an access token.
3. Access the API: Include the access token in the Authorization header of your requests.

Required Parameters

Include the following parameters in the request body:

• grant_type: Set this to password
• client_id: Your assigned client ID
• username: The user's email address
• password: The user's password

Example Request

POST /realms/partner/protocol/openid-connect/token HTTP/1.1
Host: auth.kotini.co
Content-Type: application/x-www-form-urlencoded

grant_type=password&client_id=your_client_id&username=user@example.com&password=user_password

This method is ideal for web applications and provides a more secure authentication process.

Authentication Steps

1. Authorization Request: Redirect the user to the authorization URL.
2. User Authentication: The user logs in and grants permission to your application.
3. Authorization Code: Receive an authorization code.
4. Token Request: Exchange the authorization code for an access token.
5. Access the API: Use the access token to make API requests.

Authorization Request Parameters

• response_type: Set this to code
• client_id: Your assigned client ID
• redirect_uri: Your application's callback URL
• scope: Requested permissions (e.g., openid profile email)
• state: A unique string to prevent CSRF attacks

Example Authorization Request

https://auth.kotini.co/realms/partner/protocol/openid-connect/auth?
response_type=code&
client_id=your_client_id&
redirect_uri=https://your-app.com/callback&
scope=openid profile email&
state=random_state_string

Token Request

After receiving the authorization code, exchange it for an access token:

POST /realms/partner/protocol/openid-connect/token HTTP/1.1
Host: auth.kotini.co
Content-Type: application/x-www-form-urlencoded

grant_type=authorization_code&
client_id=your_client_id&
client_secret=your_client_secret&
code=received_authorization_code&
redirect_uri=https://your-app.com/callback

Once you've obtained the access token (via either method), include it in the Authorization header of your API requests:

GET /api/v1/cases HTTP/1.1
Host: partner.service.kotini.co.uk
Authorization: Bearer <access_token>

• Always use HTTPS for all API interactions.
• Store client IDs, secrets, and user credentials securely.
• Never expose sensitive information in client-side code.
• Implement proper error handling for authentication failures.
• For the Authorization Code flow, validate the state parameter to prevent CSRF attacks.
• Consider implementing token refresh mechanisms for long-lived sessions.

Remember to replace placeholder values (like your_client_id, etc.) with your actual values when implementing the authentication flows.

Webhook operations

Case operations

Property operations