[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"doc-\u002Fdocumentation\u002Fbring-your-own-number\u002Fbyon-link-user-lines":3},{"docData":4,"isAuthenticated":10,"isTOCHidden":10,"commonDAProps":90},{"id":5,"title":6,"superTitle":7,"description":7,"sectionOrder":8,"slug":9,"isAuthenticated":10,"isTOCHidden":10,"createdAt":11,"updatedAt":12,"publishedAt":13,"environments":14,"isDeprecated":7,"deprecationNoticeTitle":7,"deprecationNotice":7,"documentId":18,"forPartnerDashboard":7,"parent_page":7,"children_pages":19,"pageContent":20},202,"Link User Lines",null,7002,"byon-link-user-lines",false,"2024-01-04T23:12:22.610Z","2025-02-16T20:51:26.662Z","2024-01-26T04:48:59.869Z",[15,16,17],"partner","preprod","production2","fo11ddktal6igja9me1z75gg",[],[21,25,64,67,87],{"__component":22,"id":23,"content":24,"referenceURL":7},"content-components.markdown",104,"To enable your application to begin making and receiving calls, it will first need to:\n- Allow a user to authorize the application to use their T-Mobile line\n- Provide users the ability to unlink their lines from your application\n\n## Authentication and Line Selection Flow\n\nTo outline the flow by means of an example, suppose your user Sam is using your application Talker on a VR headset. To start your application, Sam selects Talker from their installed applications list. Once Talker starts, a Login button is displayed.\n\nWhen Sam presses Login, your application will call the endpoint **\u002Fv1\u002Faccount-mgmt\u002FlinkAccount** (see the Swagger for NaaS-CPaaS Essential APIs 1.20, in the [API Reference](\u002Fdocumentation-hub\u002Fbring-your-own-number\u002Fbyon-api-reference) for more details).\n\n```\ncurl -X 'GET' 'https:\u002F\u002Fnaas.t-mobile.com\u002Fcpaas\u002Fv1\u002Faccount-mgmt\u002FlinkAccount?client_id=tmon-test&device_id=urn%3Auuid%3A01EC2863-132B-8675-QE2B-22A2P66E4DF5&client_secret=YGYGJBbybybvy&state=abcd&redirect_uri=http%3A%2F%2Flocalhost%3A5309' -H 'accept: \\*\u002F\\*'\n```\n\nT-Mobile responds with a URL for a login page to be rendered in Talker, for example, by an embedded browser window. The customer then enters their T-Mobile ID credentials, like logging into \u003Chttps:\u002F\u002Faccount.t-mobile.com> ; this is a sequence of screens that prompt for an email or phone number, then a password, then a two-factor authentication (2FA) code. Once completed with valid credentials, T-Mobile presents Sam with a list of phone line options, from a list of assigned lines in Sam’s T-Mobile account.\n\nOnce Sam selects a line (displayed as a phone number), T-Mobile will display the associated Emergency 911 (E911) real physical address, to be sent as Sam’s location to route emergency services. Sam can either confirm the E911 address or update the address via a T-Mobile-supplied web form. Finally, T-Mobile collects consent by displaying _Terms of Use_ and waits for Sam to agree with said terms.\n\nAt this point, control returns to the Talker app, as T-Mobile uses the **redirect_uri** submitted in the GET **\u002Fv1\u002Faccount-mgmt\u002FlinkAccount** call to point back to Talker and passes an **auth_code** as a URI parameter. Using this **auth_code**, Talker then generates and signs a proof-of-possession (PoP) token using T-Mobile’s TAAP library, which then provides an application access token.\n\nSo, at this point, the initial Authorization flow has ended for Sam, the user, and the application’s Authorization flow begins for Talker. Talker needs to call the endpoint **\u002Foauth\u002Fv1\u002Ftoken** (see the Swagger for NaaS-CPaaS Essential APIs 1.2.0, in the file **NaaS-BYON-Requisite-services-v1.2.1.yaml** for more details).\n\n```\ncurl -X 'POST' 'https:\u002F\u002Fnaas.t-mobile.com\u002Fcpaas\u002Foauth\u002Fv1\u002Ftoken' -H 'accept: application\u002Fjson' -H 'X-Authorization: \u003C\u003CPop-Token>>' -H 'transactionId: aTransactionId' -H 'Content-Type: application\u002Fx-www-form-urlencoded' -d 'grant_type=authorization_code&code=auth_code&redirect_uri=https%3A%2F%2Flocalhost%3A8000&refresh_token='\n```\n\nSince this is the first requested grant, **grant_type** will be **authorization_code**, whereas subsequent grants will be to refresh an existing access token, using the **grant_type** of **refresh_token**. T-Mobile’s API response will look something like the following:\n\n```\n{\n\"access_token\": \"eyJraWQiOiI5ZmFiYjRmNy0xNTc0LTRhZTktYTc0Zi0wZTI5M2I3MTExOGUiLCJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9.eyJzdWIiOiJ0bW9uLWdZeEsyNXJYc3NpRXJDdXZCMzkzMGxhN0N6ZDVRYnN0IiwiYXVkIjoidG1vbi1nWXhLMjVyWHNzaUVyQ3V2QjM5MzBsYTdDemQ1UWJzdCIsImlzcyI6Imh0dHBzOlwvXC9hcGktZGV2c3RnLnQtbW9iaWxlLmNvbVwvb2F1dGgyXC92MSIsImV4cCI6MTcxMjgwMDE1NiwiaWF0IjoxNzEyNzk2NTU2LCJqdGkiOiI2YmZhNmYxYi05ZDE4LTQ2ZjItYjE2OC0wMjY3YzBkMGJmM2YifQ.ccszzZ-KnGoPDL1xdoyh0dIujVnijd1npQxLq7yRUjG5mM_0hJSiAmIa4DShXMRbkmtvG_h1JhYMQzLjJZn1M6kUF3afIG0CbCpHH-u2Qveg1F_aLP_mgH7Of_xzjXJ4YG7I6g1WQQD-G_\\_TeqroO_28J8VNIjpLu78vbhQMCmkEg3inqIB0ejFsAcjntYWAt0ZXh-h82i52K27TKmOaoif1AnSjenD1uBi9i9vkC89WNpd9hI0yzPj070QenLOqelFRWvhrcqnhtiXVIzJi1zVAHeICgsBpJJasqCkG2JJZH6N8KkOf7LRQIhmfrX3Ms5GHonFRExJcZ0DapVNTbw\",\n\"refresh_token\": \"eyJraWQiOiI5ZmFiYjRmNy0xNTc0LTRhZTktYTc0Zi0wZTI5M2I3MTExOGUiLCJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9.eyJzdWIiOiJ0bW9uLWdZeEsyNXJYc3NpRXJDdXZCMzkzMGxhN0N6ZDVRYnN0IiwiYXVkIjoidG1vbi1nWXhLMjVyWHNzaUVyQ3V2QjM5MzBsYTdDemQ1UWJzdCIsImlzcyI6Imh0dHBzOlwvXC9hcGktZGV2c3RnLnQtbW9iaWxlLmNvbVwvb2F1dGgyXC92MSIsImV4cCI6MTcxMjgwMDE1NiwiaWF0IjoxNzEyNzk2NTU2LCJqdGkiOiI2YmZhNmYxYi05ZDE4LTQ2ZjItYjE2OC0wMjY3YzBkMGJmM2YifQ.ccszzZ-KnGoPDL1xdoyh0dIujVnijd1npQxLq7yRUjG5mM_0hJSiAmIa4DShXMRbkmtvG_h1JhYMQzLjJZn1M6kUF3afIG0CbCpHH-u2Qveg1F_aLP_mgH7Of_xzjXJ4YG7I6g1WQQD-G_\\_TeqroO_28J8VNIjpLu78vbhQMCmkEg3inqIB0ejFsAcjntYWAt0ZXh-h82i52K27TKmOaoif1AnSjenD1uBi9i9vkC89WNpd9hI0yzPj070QenLOqelFRWvhrcqnhtiXVIzJi1zVAHeICgsBpJJasqCkG2JJZH6N8KkOf7LRQIhmfrX3Ms5GHonFRExJcZ0DapVNTbw\",\n\"token_type\": \"Bearer\",\n\"expires_in\": 86400\n}\n```\n\n## Linking a User's T-Mobile Line\n\nThe diagram below describes the OAuth flow we've just outlined: \n\n1. Retrieve the login page provided by T-Mobile with **GET \u002Fv1\u002Faccount-mgmt\u002FlinkAccount**. The response will be a web form you can present to the user, allowing them to enter their T-Mobile login credentials.\n2. As part of this flow, the user will select the T-Mobile line to be used with your application. This is the line your application will be authorized to use. In case an error is encountered during this step, we recommend to check the list of “signed in devices” on the MyDIGITS portal. Refer to the section [Managing users signed-in instances](https:\u002F\u002Fmydigits.t-mobile.com\u002F).\n3. Once the user completes the form, they will be redirected to the URL you registered for your application. The request sent to this URL will provide you with an Authorization code and a PoP token that can be used to get your application's access token by calling **\u002Foauth\u002Fv1\u002Ftoken**.\n4. Use the access token to register your client with the network for use with this line. The response will provide you with two key items needed for the next steps: \n    - The URL to be used to establish the connection with the T-Mobile network and begin receiving network notifications ([docs](#))\n    - The phone number the user selected to be used with your application\n",{"__component":26,"id":27,"title":7,"imageLink":7,"alt":7,"width":28,"height":7,"align":29,"maxWidth":7,"imgsrc":30},"content-components.image",805,"650","left",{"id":31,"name":32,"alternativeText":7,"caption":7,"width":33,"height":34,"formats":35,"hash":57,"ext":37,"mime":40,"size":58,"url":59,"previewUrl":7,"provider":60,"provider_metadata":7,"createdAt":61,"updatedAt":61,"documentId":62,"publishedAt":63,"focalPoint":7},3288,"BYON Login and Line Selection.png",587,881,{"small":36,"medium":45,"thumbnail":51},{"ext":37,"url":38,"hash":39,"mime":40,"name":41,"path":7,"size":42,"width":43,"height":44},".png","\u002Fuploads\u002Fsmall_BYON_Login_and_Line_Selection_af0537427a.png","small_BYON_Login_and_Line_Selection_af0537427a","image\u002Fpng","small_BYON Login and Line Selection.png",72.67,333,500,{"ext":37,"url":46,"hash":47,"mime":40,"name":48,"path":7,"size":49,"width":44,"height":50},"\u002Fuploads\u002Fmedium_BYON_Login_and_Line_Selection_af0537427a.png","medium_BYON_Login_and_Line_Selection_af0537427a","medium_BYON Login and Line Selection.png",127.51,750,{"ext":37,"url":52,"hash":53,"mime":40,"name":54,"path":7,"size":55,"width":23,"height":56},"\u002Fuploads\u002Fthumbnail_BYON_Login_and_Line_Selection_af0537427a.png","thumbnail_BYON_Login_and_Line_Selection_af0537427a","thumbnail_BYON Login and Line Selection.png",12.59,156,"BYON_Login_and_Line_Selection_af0537427a",22.29,"\u002Fuploads\u002FBYON_Login_and_Line_Selection_af0537427a.png","local","2024-05-23T00:51:19.756Z","dlgf4c45tufj7l4msp2e6o53","2025-12-02T16:30:53.578Z",{"__component":22,"id":65,"content":66,"referenceURL":7},105,"## Unlinking Accounts\n\nLinked users must also be able to deauthorize their lines from use by your application. To do so, the application must invoke the Unlink Account API, which ensures that:\n\n- The user's session is expired\n- Any active registration of user’s phone line on the network is removed\n\nTo unlink a user, use **DELETE \u002Fv1\u002Faccount\u002Funlink** as described in the [API Reference](\u002Fdocumentation-hub\u002Fbring-your-own-number\u002Fbyon-api-reference). Note that the API will determine the user to be unlinked based on the authentication provided with the request, and no other body or URL parameters are needed.",{"__component":26,"id":68,"title":7,"imageLink":7,"alt":7,"width":69,"height":7,"align":29,"maxWidth":7,"imgsrc":70},806,"450",{"id":71,"name":72,"alternativeText":7,"caption":7,"width":73,"height":74,"formats":75,"hash":82,"ext":37,"mime":40,"size":83,"url":84,"previewUrl":7,"provider":60,"provider_metadata":7,"createdAt":85,"updatedAt":85,"documentId":86,"publishedAt":63,"focalPoint":7},3289,"BYON line unlink.png",460,396,{"thumbnail":76},{"ext":37,"url":77,"hash":78,"mime":40,"name":79,"path":7,"size":80,"width":81,"height":56},"\u002Fuploads\u002Fthumbnail_BYON_line_unlink_0f00eada7e.png","thumbnail_BYON_line_unlink_0f00eada7e","thumbnail_BYON line unlink.png",19.01,181,"BYON_line_unlink_0f00eada7e",13.89,"\u002Fuploads\u002FBYON_line_unlink_0f00eada7e.png","2024-05-23T00:52:16.535Z","vh096dd1wyzezcp3jzf1e277",{"__component":22,"id":88,"content":89,"referenceURL":7},130,"After the unlink endpoint has been called, the application will not be able make any CPaaS API calls using the same access token. The user must authorize the application again using the T-Mobile OAuth process to allow the application to use the APIs again.\n\n## Managing Users' Signed-in Instances\n\nUsers of your application may want a way to review the applications they have authorized to use their account. To build this into your application, you can host a reference to the URL [https:\u002F\u002Fmydigits.t-mobile.com](https:\u002F\u002Fmydigits.t-mobile.com\u002F), where users can review whether their account has been used to login to your application, and be presented with an option to unlink your application from their account. Doing so will invalidate the access of user’s account on your application. If they follow this flow to unlink their account using the unlink endpoint described in the previous section.\n\nAlternatively, the application user can do this on the T-Mobile website as well (that is, outside your application) using the following steps:\n\n1. Go-to **[the Consumer Portal](https:\u002F\u002Fmydigits.t-mobile.com\u002F)**. Use any browser to access the portal using their same T-Mobile credentials used for Bring Your Own Number on your application.\n2. Go to **“Manage signed in devices” section**\n3. View **the BYON application instance**. This would show up here along with other application instances using BYON or DIGITS offering for same T-Mobile ID\n4. Click on **Sign out**. This will show a confirmation pop-up and the user can select “SIGN OUT” option to revoke permissions from your application.\n",{"docPagePath":91,"pageName":92},"documentation>bring-your-own-number>byon-link-user-lines","documentation"]