Merchant Finder

super.AI mercahnt finder, high performance, high precision, easy to use, ready for production

Swagger API: https://merchant-prod.super.ai/swagger

Submitting Batches for Processing¶

This section provides an overview of how to submit batches for processing to the /api/v1/ipv/batches/ endpoint. It includes input requirements and a detailed explanation of the expected output.

Input Requirements¶

When submitting data for processing, ensure that your input is in JSON Lines format and includes the following keys. If the keys are not exactly as specified, the input will be rejected:

{
  "ID": "SEFD1423233",
  "MerchantName": "STARBUCKS 3211",
  "MerchantCity": "Berlin",
  "MerchantState": "",
  "MerchantZip": "13088",
  "MerchantCountry": "GERMANY",
  "MerchantNameSecondary": "",
  "MerchantCitySecondary": "",
  "MerchantStreetAddress": "",
  "MerchantStateSecondary": "",
  "MerchantZipSecondary": "",
  "MerchantCountrySecondary": "GERMANY",
  "filename": "1.csv"
}

Output Explanation¶

Once the batch is processed, the output will be a JSON object containing detailed information about the submitted merchant data. Below is an explanation of the various fields present in the output:

General Merchant Information¶

Specific Store Matching Information¶

Brand and Enterprise Information¶

User Management¶

This section covers the essential user management processes within our system, including user creation, password changes, and authentication. User accounts are currently created by super.ai, and users are notified via email which includes initial login details. For security, users must change their initial password using specific AWS commands. Once the password is updated, users can authenticate to receive an access token, enabling them to manage API keys and access other system endpoints.

User Creation Process¶

Currently, user accounts are set up exclusively by super.ai. Once an account is created:

1. Confirmation Email: The user will receive a confirmation email at the address provided during registration.
2. Password Setup: The email contains initial login credentials and instructions for setting a new password.

Password Change Process¶

To change your password, follow these steps:

1. Initiate Password Change: Open your terminal, and run the following command. Replace <EMAIL> and <INITIAL PASSWORD> with the credentials from your invitation email.

aws cognito-idp initiate-auth --client-id 3873a1pma19r4f2oug9actik46 --auth-flow USER_PASSWORD_AUTH --auth-parameters USERNAME=<EMAIL>,PASSWORD=<INITIAL_PASSWORD> --region eu-central-1

This command will return a session hash.

1. Complete Password Change: Copy the session hash from the previous step. Run the following command, replacing <SESSION_FROM_THE_PREVIOUS_STEP>, <EMAIL>, and <NEW_PASSWORD>:

   aws cognito-idp respond-to-auth-challenge --client-id 3873a1pma19r4f2oug9actik46 --challenge-name NEW_PASSWORD_REQUIRED --session <SESSION_FROM_THE_PREVIOUS_STEP> --challenge-responses USERNAME=<EMAIL>,NEW_PASSWORD=<NEW_PASSWORD> --region=eu-central-1
   

   Once executed, your password will be successfully updated.

Authentication and API Access¶

After setting or changing your password, you can authenticate to access the system:

1. Authentication Command:

aws cognito-idp initiate-auth --client-id 3873a1pma19r4f2oug9actik46 --auth-flow USER_PASSWORD_AUTH --auth-parameters USERNAME=<EMAIL>,PASSWORD=<PASSWORD> --region eu-central-1

This will provide you with a response containing your RefreshToken and AccessToken.

1. Using the AccessToken:
2. Validity: The access token is valid for up to 24 hours.
3. API Key Management: Use the access token to create, list, or delete API keys through the /auth endpoint.
4. Accessing Other Endpoints: All other API endpoints must be accessed using the API key generated from the /auth endpoint.

Note

• The /auth endpoints require an AccessToken for all operations.
• Ensure that all commands are executed in the correct AWS region (eu-central-1) as specified.

This documentation aims to guide you through the initial setup and routine operations required to effectively utilize our API services. For additional support, please refer to the contact details provided in our documentation site.

Security Overview¶

This section provides an in-depth look at the security measures and concepts implemented within our system. The primary focus is on user authentication, data protection, and secure access to API endpoints.

User Authentication and Session Management¶

1. AWS Cognito: We utilize AWS Cognito for handling all aspects of user authentication. This includes initial authentication during login and subsequent token-based session management.

2. Secure Authentication Flow: The user initiates authentication by submitting their credentials via a command-line interface, ensuring that sensitive information is not exposed through less secure methods like browser-based forms.

3. Session Tokens: Upon successful authentication, AWS Cognito issues JSON Web Tokens (JWTs), including an ID Token, Access Token, and a Refresh Token. These tokens are encrypted and designed to ensure that they are tamper-resistant.

4. Password Management:

5. Initial Passwords: Initial passwords provided in the user invitation email are temporary and require immediate change upon first login. This process is enforced through a Cognito authentication challenge.

6. Password Policies: We enforce strong password policies requiring a mix of upper and lower case letters, numbers, and symbols. Passwords must be changed regularly, and previous passwords are disallowed on reset.

Data Encryption¶

1. Data at Rest: All sensitive data stored within our databases and storage solutions are encrypted using industry-standard encryption protocols, such as AES-256.

2. Data in Transit: We use TLS 1.2 and above for all data transmitted between client devices and our servers. This ensures that data remains encrypted as it travels across the network, protecting against eavesdropping and man-in-the-middle attacks.

API Security¶

1. API Authentication: Access to our API is secured using the OAuth 2.0 framework. Users must authenticate via AWS Cognito to receive an Access Token, which is then used to make API requests.

2. Scoped Access: Tokens are scoped to limit permissions based on the user's role and the specific requirements of the application. This minimizes the potential impact of a compromised token.

3. Token Expiry: Access tokens have a short expiry time (24 hours), reducing the risk of token theft and reuse.

4. API Gateway Security:

5. Throttling and Rate Limiting: We implement rate limiting to protect against denial-of-service (DoS) attacks and to manage the load on our backend services.

6. Endpoint Monitoring: All API endpoints are monitored for unusual access patterns or potential security breaches. Alerts are generated for rapid response by our security team.

Incident Response¶

1. Rapid Response: We have an established incident response plan that includes immediate isolation of affected systems, detailed investigations, and communication with affected users and regulatory bodies as necessary.

2. Continuous Improvement: Findings from incidents are used to further strengthen our security posture and refine our response strategies.

This security architecture is designed to protect against a wide range of digital threats while ensuring the confidentiality, integrity, and availability of our users' data. Our commitment to security is integral to our operations, and we continuously strive to enhance our security measures in response to evolving threats.