swagger: '2.0' info: description: The API allows channels such as MyMTN to login, request an OTP code and request a token. The API is utilised by ZSMART partners. This API is currently utilised by MTN Rwanda. version: '1.0' title: User Authentication API termsOfService: urn:tos contact: {} license: name: Apache 2.0 url: http://www.apache.org/licenses/LICENSE-2.0 host: rwanda.api.mtn.com basePath: /v1/userauth/ schemes: - https consumes: - application/json produces: - application/json securityDefinitions: ApiKeyAuth: type: apiKey name: X-API-Key in: header security: - ApiKeyAuth: [] tags: - name: Authenticate User paths: /user/login: post: tags: - Authenticate User summary: get login into MyMTN description: This operation retrieves a login result detail operationId: loginMyMtnUsingPOST consumes: - application/json produces: - application/json parameters: - name: channel in: query description: channel required: false type: string - name: countryCode in: header description: countryCode required: false type: string - name: loginId in: query description: loginId required: true type: string - name: otp in: header description: otp required: false type: string - name: secret in: header description: secret required: true type: string - name: userType in: query description: userType required: false type: integer format: int32 responses: '200': description: OK schema: $ref: '#/definitions/LoginDetail' '201': description: Created '401': description: Unauthorized '403': description: Forbidden '404': description: Not Found deprecated: false /user/otp: post: tags: - Authenticate User summary: get OTP description: This operation creates an OTP operationId: createOtpAggUsingPOST consumes: - application/json produces: - application/json parameters: - name: channel in: query description: channel required: false type: string - name: countryCode in: header description: countryCode required: false type: string - name: loginId in: query description: loginId required: true type: string - name: userType in: query description: userType required: false type: integer format: int32 responses: '200': description: OK schema: $ref: '#/definitions/GetOtpDetail' '201': description: Created '401': description: Unauthorized '403': description: Forbidden '404': description: Not Found deprecated: false /user/token: post: tags: - Authenticate User summary: get authorization token description: This operation provides the ability for a zsmart partner to create a token or get an existing token. operationId: createTokenUsingPOST consumes: - application/json produces: - application/json parameters: - in: body name: authorizationDetails description: Details entered by the partner as registerd on the zsmart App to create a token required: true schema: $ref: '#/definitions/authorizationDetails' responses: '200': description: OK schema: $ref: '#/definitions/GetTokenDetail' '400': description: Bad Request schema: $ref: '#/definitions/Error' '401': description: Unauthorized schema: $ref: '#/definitions/Error' '403': description: Forbidden schema: $ref: '#/definitions/Error' '404': description: Not Found schema: $ref: '#/definitions/Error' definitions: APIResponse: type: object properties: _links: type: array xml: name: link attribute: false wrapped: false items: $ref: '#/definitions/Link' statusCode: type: string title: APIResponse GetOtpDetail: type: object properties: _links: type: array xml: name: link attribute: false wrapped: false items: $ref: '#/definitions/Link' resultCode: type: string resultDescription: type: string statusCode: type: string title: GetOtpDetail GetTokenDetail: type: object required: - data - statusCode - statusMessage - transactionId properties: statusCode: type: string description: This is the MADAPI Canonical Error Code (it is 4 characters long and it is not the HTTP Status Code which is 3 characters long). Back-end system errors are mapped to specific canonical error codes which are returned. More information on these mappings can be found on the MADAPI Confluence Page 'Response Codes' example: '00000' statusMessage: type: string description: More details and corrective actions related to the error which can be shown to a client. example: 'Operation Success' transactionId: type: string description: MADAPI generated Id to include for tracing requests example: "1365478abcz-fdhsdfh54351" data: type: object required: - status properties: accessToken: type: string description: "App token" example: "N2U5MTM3M2VmYzBhY2U4MmY2YWFlODMyODJhN2ZiZWE=" expireDate: type: string description: "App token expire date. If the app does not configure ‘Token Validity’, this value will be empty." example: "2023-03-24 16:57:14" expireIn: type: number description: "App token validity. The Unit is in seconds. If the app does not configure ‘Token Validity’, this value will be 0." example: 3600 title: GetTokenDetail Link: type: object properties: deprecation: type: string xml: name: deprecation attribute: true wrapped: false href: type: string xml: name: href attribute: true wrapped: false hreflang: type: string xml: name: hreflang attribute: true wrapped: false media: type: string xml: name: media attribute: true wrapped: false rel: type: string xml: name: rel attribute: true wrapped: false templated: type: boolean title: type: string xml: name: title attribute: true wrapped: false type: type: string xml: name: type attribute: true wrapped: false title: Link authorizationDetails: type: object required: - appSecret - appCode - responseType - timestamp - sign properties: appCode: type: string description: 'App Code, generated when creating the APP, and can be viewed on' example: 'OAuthTest' appSecret: type: string description: 'Secret Key, generated when creating the APP, and can be viewed on ‘APP Configuration’ interface.' example: '514541be484acd57' responseType: type: string description: 'Hardcode token - Authorization type' example: 'token' timestamp: type: string description: '13-digit millisecond-level timestamp.e.g.: 1679666201373' example: '1679666201373' privateKey: type: string description: 'Private Key generated when creating the APP, and can be viewed on ‘APP Configuration’ interface.' sign: type: string description: 'Sign, generated by MD5WithRSA encryption with appCode, appSecret, responseType, timestamp, and Private Key.' example: 't1ylJWTxgW1uRRzzKJK8BQISLj9HmAVJ1Dsc3EpVJnY+oo5PLv48DyYDqflbl300Mu4Sg4BYft6msdWqoY1Cnbn+laEeWPLDyxshrw2X8hsrJilrQoQVOnU5B21C+BpnhAwUzaSEWMjbc9ubGvmqTrRytXTPR4EiFwYLwal0W+58XeCqnqtUyi6h62p9RUTnsoYfLzLz4qo69BoH8swxSiwDz9qgBIRSKFEpgVaOKYZ+mfR3zMv03V/bB7H+MpKWTJfN50pDBZvviUa/lzLTwAzhPxaw9KatIfawVJIECBj+EH5ge3kvgm3RSLchEk+QtVf2GyoOmQL7I2BdV76tFg==' force: type: boolean description: 'If the value is true, APIG will forcibly refresh the App’s token and return. If the value is false or not send, APIG will return the available token, if the token has expired, APIG will refresh and return the new token.' default: false title: authorizationDetails LoginDataDetail: type: object properties: id: type: string message: type: string title: LoginDataDetail LoginDetail: type: object properties: _links: type: array xml: name: link attribute: false wrapped: false items: $ref: '#/definitions/Link' data: $ref: '#/definitions/LoginDataDetail' resultCode: type: string resultDescription: type: string statusCode: type: string title: LoginDetail Error: type: object required: - "statusCode" - "statusMessage" - "transactionId" properties: statusCode: type: string description: This is the MADAPI Canonical Error Code (it is 4 characters long and it is not the HTTP Status Code which is 3 characters long). Back-end system errors are mapped to specific canonical error codes which are returned. More information on these mappings can be found on the MADAPI Confluence Page 'Response Codes' statusMessage: type: string description: More details and corrective actions related to the error which can be shown to a client supportMessage: type: string description: Internal message meant for consumers of the API to troubleshoot the error (could possible include the back-end system error code in the message if it would be useful) transactionId: type: string description: MADAPI generated Id to include for tracing requests timestamp: type: string format: date-time description: Timestamp that the error occurred example: '2020-08-01T12:34' path: type: string description: The path that caused the error example: 'https://api.mtn.com/v1/' method: type: string description: The HTTP method type that was used example: 'POST'