Joshua Ogden 1/10
About
CVS is a microservice for generating, sending, and validating one-time pins. Additionally, CVS
can be used for generating & validating T-Mobile security compliant passcodes.
Environments
A firewall request with likely be required for connectivity to the Conducktor cloud environment
hosting CVS and the IAM (for bearer token generation). Internet facing NAT IP's will also need
whitelisted in the CVS production WAF and can be sent to the CVS Engineering email
distribution.
Production
CVS
FQDNs Subnets
cvs.t-mobile.com 45.60.11.176
45.60.13.176
45.60.15.176
45.60.17.176
45.60.19.176
45.60.101.176
IAM
FQDN VIPs
ws.msg.t-mobile.com 10.175.100.25
10.188.100.25
10.175.88.25
10.188.88.25
Lab
Staging
FQDNs STG Subnets
iamcustomlab.t-mobile.com 10.65.58.0/24
10.65.59.0/24
2019-10-21
Joshua Ogden 2/10
FQDNs STG Subnets
10.65.60.0/24
10.65.61.0/24
10.65.62.0/24
10.65.63.0/24
Performance
FQDNs Subnets
iamcustomplab.t-mobile.com 10.65.58.0/24
10.65.59.0/24
10.65.60.0/24
10.65.61.0/24
10.65.62.0/24
10.65.63.0/24
IAM
For CVS Staging Lab
FQDNs Subnets
ws14.iam.msg.lab.t-mobile.com 10.174.200.133
For CVS Performance Lab
FQDNs VIP
ws5.iam.msg.lab.t-mobile.com 10.174.200.133
API Reference
Endpoints
Endpoint Description
/custom/v1/generatepin Generates, store, and send a one-time pin
/custom/v1/validatepin Validates a previously generated pin
/custom/v1/generaterandompasscode Generated a random number usable as a pin
/custom/v1/validatepinformat Validates format and complexity of a pin
2019-10-21
Joshua Ogden 3/10
Endpoint Description
/custom/v1/healthcheck Indicates service and database health
Generate PIN
/custom/v1/generatepin
Requires and IAM trusted token
Token is validated by calling IAM
Queries the IAM for a user profile
UserInfoV1: Extracts customer name for use in emails. When no profile exists
'Customer' is used
UserInfoV2: Extracts UID for PIN storage in database. When no profile exists the
id field is used for storage
SMS sent via SDG
Emails sent via Tibco to Broadridge
Allows multiple PINs per user
Encrypts PINs
Sends pins to LADEX status subscribers
Supports variety templates for SMS and email delivery options
Interface
Header Example Description
Authorization Bearer 1.SYS.23456789abcd Required. IAM Trusted Token.
X- 08c85dc2-e938-42ef-a1f1- Required. UUID recommended. Call
Correlation- bf256cc0c6f5 tracing aid.
ID
Accept application/json Optional. Only JSON responses are
accepted.
Query Example Description
Parameter
msisdn:2531234567 Required. User Identifier.
id email:E2531234567@yopmail.com Supports a 10 digit MSISDN or Email
address.
Optional. Delivery Methods. Default:
sms
delivery response sms Allowable PIN delivery methods: sms
response email
Delivery method must user identifier
type from id parameter.
2019-10-21
Joshua Ogden 4/10
Query Example Description
Parameter
Optional. PIN TTL. Default: 72h
expiry 1h Time base specified by: s-second,
m-minute, h-hour, or d-day.
Only one may be specified.
length 6 Optional. PIN Length. Default: 6
Minimum: 6, Maximum: 15
max_attempts 3 Optional. Maximum allowable
attempts. Default: 3
Optional. PIN Type. Default: numeric
type numeric Options include: numeric,
alphanumeric, limited (excludes
visually similar characters).
Optional. Default: false
force_new false Generates new PIN even if a valid PIN
exists.
Validate PIN
/custom/v1/validatepin
Requires and IAM trusted token
Token is validated by calling IAM
Queries the IAM for a user profile
UserInfoV2: Extracts UID for PIN lookup in database. When no profile exists the id
field is used for the lookup
Checks PIN against all valid PINs belonging to the user
Will delete any invalid PINs for the user
Generate Passcode
/custom/v1/generaterandompasscode
Generates a random passcode that complies with /custom/v1/validatepinformat
complexity rules
Validate Password Format
/custom/v1/validatepinformat
Checks that the PIN passes the following rules:
Minimum length >= 6
Maximum length <= 15
Repeated characters >= 4
Consecutive sequences >= 4
Healthcheck
2019-10-21
Joshua Ogden 5/10
/custom/v1/healthcheck
Returns a JSON payload
Example API Calls
Acquiring a Bearer Token
An IAM bearer token is required to call generate pin and validate pin. The necessary IAM client
credentials require onboarding with the IAM team, who for CVS related purposes can be
contacted by emailing the CVS Engineering.
Request
Note: The Authorization header should be of the form Bearer clientid:secret where
clientid:secret is Base64 encoded.
User-Agent: python-requests/2.18.4
Accept-Encoding: gzip, deflate
Accept: */*
Connection: keep-alive
Content-Type: application/x-www-form-urlencoded
Authorization: Basic <Base64 encoded clientid:secret>
Content-Length: 0
Response
HTTP/1.1 200
Date: Fri, 18 Oct 2019 20:00:44 GMT
Cache-Control: no-store
Pragma: no-cache
Content-Type: application/json
Content-Length: 108
{
"access_token": "14.SYS.v12***",
"token_type": "Bearer",
"scope": "TMO_ID_profile",
"expires_in": 3600
}
Generating a PIN
Curl Request
curl -X GET \
'https://iamcustomlab.t-mobile.com/custom/v1/generatepin?
2019-10-21
Joshua Ogden 6/10
id=msisdn:2532234628&delivery=sms%20response' \
-H 'Accept: application/json' \
-H 'Authorization: Bearer <trusted token>'
Responses
Success (200 OK)
{
"expiry_time": "2019-03-08T23:36:56.866Z",
"pin": "123443"
}
PIN Delivery Failure (500 Internal Server Error)
{
"error_code": "pin_delivery_failed",
"error_description": "PIN delivery was not successful"
}
Server Error (500 Internal Server Error)
{
"error_code": "internal_error",
"error_description": <mutable description where possible>
}
The following errors are not expected during runtime; however, these errors may occur
during the development process.
Missing Request Parameter (400 Bad Request)
{
"error_code": "missing_parameters",
"error_description": <list of missing parameters>
}
Invalid Request Parameters (400 Bad Request)
{
"error_code": "invalid_request",
"error_description": <list of invalid parameters>
}
2019-10-21
Validating a PIN
Joshua Ogden 7/10
Curl Request
curl -X GET \
'https://iamcustomlab.t-mobile.com/custom/v1/validatepin?
id=2532234567&pin=102373' \
-H 'Accept: application/json' \
-H 'Authorization: Bearer <trusted token>'
Response
Valid PIN (200 OK)
{}
Invalid PIN
{
"error_code": "invalid_pin"
}
User Not Found (404 Not Found)
{
"error_code": "invalid_pin"
}
User Not Found (404 Not Found)
{
"error_code": "id_not_found",
"error_description": "User not found"
}
Invalid Token (401 Unauthorized)
{
"error_code": "invalid_authorization"
}
PIN Delivery Failure (500 Internal Server Error)
2019-10-21
Joshua Ogden 8/10
{
"error_code": "pin_delivery_failed",
"error_description": "PIN delivery was not successful"
}
Server Error (500 Internal Server Error)
{
"error_code": "internal_error",
"error_description": <mutable description where possible>
}
The following errors are not expected during runtime; however, these errors may occur
during the development process.
Missing Request Parameter (400 Bad Request)
{
"error_code": "missing_parameters",
"error_description": <list of missing parameters>
}
Invalid Request Parameters (400 Bad Request)
{
"error_code": "invalid_request",
"error_description": <list of invalid parameters>
}
Generating Passcode
Example Curl Request
curl -X GET \
https://iamcustomlab.t-mobile.com/custom/v1/generaterandompasscode
\
-H 'Accept: application/json' \
-H 'Authorization: Bearer <trusted token>'
Example Response
{
"pin": "669189965700571"
2019-10-21
Joshua Ogden 9/10
}
Validating Passcode
Example Curl Request
curl -X GET \
'https://localhost:1443/custom/v1/validatepinformat?pincode=162534'
\
-H 'Accept: application/json' \
-H 'Authorization: Bearer <trusted token>'
Example Response
{
"is_valid": true
}
Healthcheck
Curl Request
curl -X GET \
'https://localhost:1443/custom/v1/healthcheck' \
-H 'Accept: application/json'
Response
{
"working": true,
"checkTime": "<time of health check on server>",
"dbConnection": "<boolean indicating database connectivity>",
"dbTotalRows": "<number of rows in the environment's database>",
"selectLatency": "<millisecond response time of worst case select>"
}
Support
Escalation Path
1. If emergency, call NOC Messaging & Data Applications – Please note if urgent PHONE
CALL (888-662-4662 opt 5 opt 8) SHOULD BE MADE – email is not an immediate
response
2019-10-21
Joshua Ogden 10/10
2. First request need to go to: Tier II Customer Access & Provisioning and IAM Engineering
3. Escalations if no response: Tier 2 Customer Access & Provisioning
Tier2CustomerAccessProvisioning@T-Mobile.com
4. Escalation if still no response: Call Kathaleen Harvey – 253-332-0021
Email
Distribution Description
Tier II Customer Access & Provisioning Operational Support
CVS Engineering Engineering Team
Splunk
A public support channel (#cvs) is available for partners to use for questions, reference
documentation, and receive updates about changes with CVS. It is NOT a place to report
production issues, for that please see the ESCALATION PATH above.
2019-10-21
