camaraproject / otpvalidationapi Goto Github PK

A new PR will be open order to align the API definition with following changes in the guidelines:

• Parameters should be named in lowerCamelCase. Issue, Discussion & PR.
• Adjust the schema references in the errors responses and apply the agreed solution: Issue & PR.

I removed the restriction for error status as in commonalities there is no agreement about limiting the integer values.

PR#22

Hi,

do we have any meetings arranged for this working group ? I'd like to get involved.

Gareth

Dear all,
I opened a PR to add Telefónica team to the maintainers list as it was agreed on steering committee of CAMARA project.
It's possible that there are more people from other companies that should be included. In that case please proceed.

Adding templates as described in https://github.com/camaraproject/WorkingGroups/blob/main/Commonalities/documentation/Issue%20and%20PR%20template%20Howto.md

PR #31

This PR was created to include documentation about the API functionality and other relevant information.

Problem description
Due to Dawid step-off, the subproject needs a new codeowner to have representation from different operators.

Since I'm already codeowner in Sim swap and Number Verification, I can be here as well.
This can be permanent or temporary if DT decides to propose a new codeowner to replace Dawid

Hi Team,

Can you support to provide detail/suggestion/comment on below points

1. '{{code}}' : do this code(OTP) will have expire,
   a. if yes do it changes from useCase to useCase.
   b. how end client will be aware of this expire duration.
2. '{{code}}': What will be length of this code (OTP). Do this length will also change from useCase to useCase.
3. Do message contain can change from case by case.
4. Do this api 'sendSMS' is specific to any country(like UAE).
5. Can the mobileNumber can be of any country.
6. For sendSMS: do 'message' field can be changed to number(messageID), so this number will define the message to be sent to phoneNumber. This will help to avoid free text which may be potential spam. A table can be created to define message with respect to messageNumber.

As we did for the code in the send-code operation, we should add maxLenght limitation in the validate-code request for authenticationId (max lenght set to 36) and code (10).

Any objection from the team?

Problem description
discuss the scope to be included in the Release

Expected action
create a first release of OTPValidation API
0.5.0

Additional context

Problem description

Links for release v0.5.0 within README.md are wrong (pointing to main instead to the release branch).
In addition the link https://github.com/camaraproject/O/tree/release-0.5.0 is broken

Expected behavior

Corrected links.

Alternative solution
n/a

Additional context
n/a

Hello
One feedback following our implementation:

• we should probably limit the length of the message attribute (to 150 characters for example)
  maxLength: 150

This is minor improvement that can probably be considered for next release.

Problem description
Running linting rule against current API specification gives the following results:

 152:18  warning  camara-properties-descriptions  Property description is missing or empty: "SendCodeBody.description" property must be truthy      components.schemas.SendCodeBody
 162:22  warning  camara-properties-descriptions  Property description is missing or empty: "SendCodeResponse.description" property must be truthy  components.schemas.SendCodeResponse
 169:22  warning  camara-properties-descriptions  Property description is missing or empty: "ValidateCodeBody.description" property must be truthy  components.schemas.ValidateCodeBody
 200:15  warning  camara-properties-descriptions  Property description is missing or empty: "ErrorInfo.description" property must be truthy         components.schemas.ErrorInfo
 217:16  warning  camara-properties-descriptions  Property description is missing or empty: "two_legged.description" property must be truthy        components.securitySchemes.two_legged

✖ 5 problems (0 errors, 5 warnings, 0 infos, 0 hints)

Results of yamllint:
one-time-password-sms.yaml

  8:193     error    trailing spaces  (trailing-spaces)
  11:24     error    trailing spaces  (trailing-spaces)
  95:11     error    wrong indentation: expected 12 but found 10  (indentation)
  149:11    error    wrong indentation: expected 12 but found 10  (indentation)
  158:47    error    trailing spaces  (trailing-spaces)
  223:98    error    trailing spaces  (trailing-spaces)

Expected behavior
Errors needs to be corrected and warnings reviewed if corrections are needed.
After implementing corrections, the Github Action can be configured in the repository to check each PR.

Alternative solution

Additional context

The guideline for errors has been changed today and now status is an integer instead of a string:

camaraproject/WorkingGroups#143
camaraproject/WorkingGroups#145

This change will be included in this PR.

camaraproject/WorkingGroups#120

Overview

This issue outlines a series of proposed enhancements to the One Time Password SMS API to improve its usability, security, and compliance. The goal is to provide a clearer, more robust, and developer-friendly API that aligns with best practices and industry standards.

Below we compare the current API specification with the suggested enhancements by providing concrete examples for each for your review:

1. Performance Metrics:

   • Current: No performance metrics are defined in the documentation.
   • Suggestion: Document expected performance metrics.
   • Example: Add to the documentation: "The API is designed to handle up to 10,000 requests per minute with an average latency of 500 ms."

2. Endpoint Descriptions:

   • Current: Endpoint descriptions are basic, with no mention of rate limits.
   • Suggestion: Add details about rate limits to endpoint descriptions.
   • Example: Add to /send-code endpoint description: "Rate limited to 100 requests per hour per phone number."

3. Error Handling:

   • Current: Generic error messages, e.g., "message": "Client specified an invalid argument, request body or query param".
   • Suggestion: Provide specific error messages and troubleshooting steps.
   • Example: Change to "message": "Invalid 'phoneNumber' format. Ensure it is in E.164 format, including the '+' sign and country code."

4. Security Schemes:

   • Current: OAuth2 security scheme with no details on token algorithm or lifecycle.
   • Suggestion: Specify token algorithm and lifecycle best practices.
   • Example: In securitySchemes, add "algorithm": "RS256" and in the description: "Tokens have a 60-minute lifetime before expiration."

5. Request and Response Bodies:

   • Current: Message maxLength: 160
   • Suggestion: Handle multi-part messages internally.
   • Example: Update the API to accept "maxLength": 640, with documentation stating: "Messages will be automatically segmented and reassembled."

6. Rate Limiting and Quotas:

   • Current: No explicit rate limiting headers or documentation.
   • Suggestion: Define and document rate limits, include headers in responses.
   • Example: Include in response headers X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset.

7. Webhooks for Asynchronous Operations:

   • Current: No webhook support.
   • Suggestion: Implement webhooks for status updates.
   • Example: Add a webhook endpoint in the documentation for status updates, e.g., "webhookUrl": "https://clientapp.com/otp-delivery-status".

8. Localization and Internationalization:

   • Current: No support for multiple languages in the Message schema.
   • Suggestion: Support multiple languages.
   • Example: Add "locale": "en-US" in the SendCodeBody schema, with a note: "Locale parameter sets the language for OTP messages."

9. Testing and Sandbox Environment:

   • Current: No separate sandbox environment URL provided.
   • Suggestion: Provide a sandbox environment URL.
   • Example: Add a sandbox URL like https://api.sandbox.example.com/one-time-password-sms/v0 for testing.

10. Monitoring and Analytics:

    • Current: No endpoints for monitoring or analytics.
    • Suggestion: Add monitoring and analytics capabilities.
    • Example: Include an endpoint GET /analytics/otp-usage to fetch usage statistics.

11. Compliance and Regulation:

    • Current: No mention of compliance with privacy regulations.
    • Suggestion: Add compliance features and documentation.
    • Example: Include a field in the request schema for user consent: "userConsent": true, with a note on GDPR compliance.

The above examples highlight the difference between the current state of the API and how each suggested improvement could be articulated within the API documentation or functionality.

Hello OTP team 👋

I hope this is an appropriate channel to ask about auth flows.

As per the title - will OTPValidation be secured by a two-legged auth flow?

I understand that the API spec currently states "two_legged" but my understanding is that CAMARA APIs will use three legged when user data is involved. I also understand from peripheral discussions that OTPValidation may remain as two legged as it has specific use cases.

I am asking in context of routing requests to target operators in a federated/aggregated model. The routing discussion is possibly out of scope of CAMARA - but you are probably aware of discussions in related forums whereby the user identifier in a three-legged auth flow can be used to facilitate routing to target operators. Client Credentials does not contain user data, and this OTPValidation use case likely needs to be taken into account in the relevant platform for routing discussions.

Thanks!

Problem description
As defined in Commonalities (here: camaraproject/Commonalities#148) we need to specify in the yaml that '+' is mandatory

Expected behavior
Change pattern & description

Alternative solution

Additional context

Hi Team ,
The send-code end point uRL has 2 request parameters mobile number and message .
The request field message has {code} in it .
I want to understand who generates this code ? Is it getting generated by the client and will he be responsible for appending it in the message or the server need to generate this code and append in the message .

Basically, is this service about only sending an SMS or generating the code and send an SMS both.

Regards
Prashant sidana