You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Service Enabling Network Function API to verify that the provided **mobile phone number** is the one used in the device. It verifies that the user is using a device with the same *mobile phone number* as it is declared.
6
+
It also makes it possible for a Service provider to verify the number itself by returning the phone number associated to the authenticated user's access token.
7
+
8
+
In this API **phone number** term refers to the mobile phone number
9
+
10
+
# API Functionality
11
+
This enables a Service Provider (SP) to verify the phone number of the mobile device being used to access their service. The mobile device can access the *service provider* over a **mobile network or WiFi connection** using **SIM-Based Authentication**. This can happen either by getting the comparison result or receiving the phone number of the device that is used, so they can verify it themselves.
12
+
13
+
# Authentication Methods
14
+
This API supports two distinct authentication methods:
15
+
- **Mobile Network Authentication**: Traditional authentication via mobile network operator infrastructure
16
+
- **SIM-Based Authentication (TS.43 Operator Tokens)**: Enhanced authentication using standardized operator tokens, supporting both mobile network and WiFi connections
17
+
18
+
The SIM-Based Authentication method enables verification over WiFi by utilizing secure tokens issued by mobile operators according to TS.43 specifications.
19
+
20
+
# Resources and Operations overview
21
+
This API currently provides two endpoints supporting **3-legged tokens** with flexible authentication methods:
22
+
- The first one checks if the user mobile phone number matches the phone number associated with the mobile device. It can receive either a hashed or a plain text phone number as input and it compares the received input with the authenticated user's phone number associated to the access token in order to respond **true/false**.
23
+
- The next one retrieves the phone number associated to the user's token and returns it so the verification can be made by the service provider.
24
+
25
+
Authentication can be performed via:
26
+
- **CIBA (Client Initiated Backchannel Authentication)** with TS.43 operator tokens
27
+
- **JWT-Bearer** authentication flows with TS.43 operator tokens
28
+
- Traditional mobile network authentication (backward compatibility)
29
+
30
+
# Sequence Diagram
31
+
Number Verification API uses **OAuth2 Authorization Code grant** and **TS.43 SIM-Based Authentication**. The following diagram will help to clarify the end-to-end process, including previous steps prior to this API call.
- **(1):** Authentication supports both automatic network-based and SIM-based methods. For SIM-based authentication, TS.43 operator tokens enable secure verification over both mobile networks and WiFi connections. Traditional SMS OTP or user/password methods remain incompatible for mobile network authentication. The use of parameter prompt=none, as described in **[OIDC Connect](https://openid.net/specs/openid-connect-core-1_0.html#AuthRequest)**, ensures no user interaction for automatic flows.
38
+
39
+
- **(2):** The way in which the phone_number is retrieved depends on the implementation and authentication method used. For TS.43 tokens, the phone number is securely embedded within the operator-issued token. For traditional access tokens, implementations may use self-contained encrypted JWT or request the phone_number from the authorization server.
Verifies if the specified phone number (plain text or hashed format) matches the one associated with the access token.
63
+
- The number verification supports multiple authentication methods: traditional mobile network authentication and **SIM-Based Authentication (TS.43 Operator Tokens)**
64
+
- For SIM-Based Authentication, verification works over both **mobile network and WiFi connections**
65
+
- The user authentication can be performed via **CIBA** or **JWT-Bearer** flows with TS.43 operator tokens
66
+
- It returns true/false depending on if the phone number received as input matches the authenticated user's `device phone number` associated to the access token
67
+
68
+
**Authentication Methods Supported:**
69
+
- Traditional mobile network authentication (backward compatibility)
70
+
- SIM-Based Authentication with TS.43 operator tokens (recommended)
Create an app on our [Sandbox](/docs/sandbox) to get credentials and [retrieve tokens](/reference/authorize) so you can perform API calls to our operators' production environments, or use the following convenience token to test in mock mode:
79
+
80
+
`mock_sandbox_access_token`
81
+
82
+
You can explore our [Number Verification sample code](/docs/samplecode_numberverification) for additional guidance on using this API.
number-verification:verify: phoneNumberVerify operation via CIBA flow
138
+
schemas:
139
+
NumberVerificationRequestBody:
140
+
type: object
141
+
description: Payload to verify the phone number
142
+
oneOf:
143
+
- $ref: '#/components/schemas/PhoneNumber'
144
+
- $ref: '#/components/schemas/HashedPhoneNumber'
145
+
PhoneNumber:
146
+
type: object
147
+
properties:
148
+
phoneNumber:
149
+
description: A phone number belonging to the user in **E.164 format (starting with country code)**. Optionally prefixed with '+'.
150
+
type: string
151
+
example: '+346661113334'
152
+
HashedPhoneNumber:
153
+
type: object
154
+
properties:
155
+
hashedPhoneNumber:
156
+
description: Hashed phone number. SHA-256 (in hexadecimal representation) of the mobile phone number in **E.164 format (starting with country code)**. Optionally prefixed with '+'. Must be exactly 64 hexadecimal characters.
description: The device phone number associated to the access token in **E.164 format (starting with country code)**. Optionally prefixed with '+'.
178
+
type: string
179
+
example: '+346661113334'
180
+
DevicePhoneNumberVerified:
181
+
description: Number verification. True, if it matches
182
+
type: boolean
183
+
ErrorInfo:
184
+
type: object
185
+
required:
186
+
- status
187
+
- code
188
+
- message
189
+
properties:
190
+
status:
191
+
type: integer
192
+
description: HTTP response status code
193
+
code:
194
+
type: string
195
+
description: Code given to this error
196
+
message:
197
+
type: string
198
+
description: Detailed error description
199
+
responses:
200
+
Generic400:
201
+
description: Problem with the client request
202
+
content:
203
+
application/json:
204
+
schema:
205
+
$ref: '#/components/schemas/ErrorInfo'
206
+
example:
207
+
status: 400
208
+
code: INVALID_ARGUMENT
209
+
message: Client specified an invalid argument, request body or query param
210
+
Generic401:
211
+
description: Authentication problem with the client request
212
+
content:
213
+
application/json:
214
+
schema:
215
+
$ref: '#/components/schemas/ErrorInfo'
216
+
example:
217
+
status: 401
218
+
code: UNAUTHENTICATED
219
+
message: Request not authenticated due to missing, invalid, or expired credentials
220
+
PhoneNumberVerificationPermissionDenied403:
221
+
description: |
222
+
Client does not have sufficient permission.
223
+
In addition to regular scenario of `PERMISSION_DENIED`, other scenarios may exist:
224
+
- Client authentication was not via supported method. Supported methods include mobile network authentication, SIM-based authentication (TS.43), CIBA flows, or JWT-Bearer flows. In order to check the authentication method, AMR parameter value in the access token can be used (`{"code": "NUMBER_VERIFICATION.USER_NOT_AUTHENTICATED_BY_SUPPORTED_METHOD","message": "Client must authenticate via mobile network, SIM-based authentication, or supported OAuth2 flows"}`)
225
+
- Phone number cannot be deducted from access token or TS.43 operator token context.(`{"code": "NUMBER_VERIFICATION.INVALID_TOKEN_CONTEXT","message": "Phone number cannot be deducted from token context"}`)
226
+
- Invalid TS.43 operator token format or signature.(`{"code": "NUMBER_VERIFICATION.INVALID_TS43_TOKEN","message": "Invalid or malformed TS.43 operator token"}`)
227
+
content:
228
+
application/json:
229
+
schema:
230
+
$ref: '#/components/schemas/ErrorInfo'
231
+
examples:
232
+
PermissionDenied:
233
+
value:
234
+
status: 403
235
+
code: PERMISSION_DENIED
236
+
message: Client does not have sufficient permissions to perform this action
0 commit comments