Creating a Service Key with the API

This topic describes the API procedure to create a service key, including how to get the Port ID (productUid) and create a VXC with a service key.

For an overview of service keys, see Setting Up Service Keys and Managing service keys. For more information on service key APIs, see Service Keys (API Documentation).

Prerequisites

Access to the Megaport Portal.
A Port, MCR, or MVE on the Megaport network.
You have a valid access token. For more information, see Creating an API Key.

To get the productUid for the Port

In Postman, click Product Details in the left navigation and select GET Product List.
Click Send.
From the returned product details, locate the productUid value for the Port for which you want to create the service key.

This example uses the following Port:
```
"productName": "CoreSite LA1" in "city": "Los Angeles" 
with "productUid": "8611b645-ea50-46eb-b400-1c2fb858a303"
```

Creating a service key

After locating the productUid value for the product for which you want to create the service key, you can use the Megaport API to create the service key.

To create a service key

In Postman, click Connections in the left navigation and select Service Keys > POST Generate Service Key.

Copy the productUid of your on-ramp (Port) and update the Body.

For this example, the value of the productUid of the Port is 8611b645-ea50-46eb-b400-1c2fb858a303.

{
    "productUid": "8611b645-ea50-46eb-b400-1c2fb858a303",
    "description": "Documentation Service Key - Single Use",
    "active": true,
    "_set_singleUse_to_false_to_make_service_key_multiUse": true,
    "singleUse": true,
    "maxSpeed": "500",
    "preApproved": true,
    "vlan": 3,
    "validFor": {
         "_make_start_timestamp_equal_to_now": 1608506197135,
         "start": 1608506197135,
         "_make_end_timestamp_equal_to_1_month_forward": 1612015200000,
         "end": 1612015200000
    }
}

Specify additional parameters in the Body, for example, rate limit (maxSpeed), how long the key will be valid (validFor), and if you need a single-use key ("singleUse": true) or multi-use key ("singleUse": false). The dates are entered in UNIX timestamp date format. You can use tools such as https://www.epochconverter.com/ or https://it-tools.tech/date-converter to determine the correct value to enter.

For single-use keys only, specify a VLAN ID (vlan).

This is the VLAN ID for the B-End. Megaport checks that the requested VLAN ID is available. When a customer uses this service key to create a connection to your Port, they can specify a VLAN ID for the A-End.

For more information on VLAN IDs, see Managing VLAN IDs.
When you are done, click Send to make the request.
```
POST /v2/service/key
```

A successful response passes validation and has a 200 OK status.

{
    "message": "New service key [106e38ae-eb59-415f-ac81-526a5299851d] generated",
    "terms": "This data is subject to the Acceptable Use Policy https://www.megaport.com/legal/acceptable-use-policy",
    "data": {
        "key": "106e38ae-eb59-415f-ac81-526a5299851d",
        "createDate": 1712277262872,
        "companyId": 1153,
        "companyUid": "160208ae-01e4-4cb9-8d57-03a197bd47a8",
        "companyName": "Megaport Lab",
        "description": "Documentation Service Key - Single Use",
        "productId": 193076,
        "productUid": "8611b645-ea50-46eb-b400-1c2fb858a303",
        "productName": "My new Port",
        "vlan": 3,
        "maxSpeed": 500,
        "preApproved": true,
        "singleUse": true,
        "lastUsed": null,
        "active": true,
        "validFor": {
            "start": 1608506197135,
            "end": 1612015200000
        },
        "expired": true,
        "valid": false,
        "promoCode": null,
        "productDto": {
            "productUid": "8611b645-ea50-46eb-b400-1c2fb858a303",
            "productName": "My new Port",
            "portSpeed": 1000,
            "locationId": 60,
            "vxcPermitted": true,
            "companyUid": "160208ae-01e4-4cb9-8d57-03a197bd47a8",
            "companyName": "Megaport Lab",
            "connectType": "DEFAULT",
            "productId": 193076,
            "productType": "MEGAPORT",
            "provisioningStatus": "LIVE",
            "createDate": 1712268634020,
            "createdBy": "0b367492-186d-47ab-96e0-34ca03d29dcd",
            "terminateDate": null,
            "liveDate": 1712268694790,
            "market": "US",
            "costCentre": "Optional finance reference",
            "usageAlgorithm": "NOT_POST_PAID",
            "marketplaceVisibility": false,
            "secondaryName": null,
            "lagPrimary": false,
            "lagId": null,
            "aggregationId": null,
            "contractStartDate": 1712268694807,
            "contractEndDate": 1714831200000,
            "contractTermMonths": 1,
            "associatedVxcs": [],
            "associatedIxs": [],
            "attributeTags": {},
            "virtual": false,
            "buyoutPort": false,
            "locked": false,
            "adminLocked": false,
            "diversityZone": null,
            "nserviceId": 521477,
            "cancelable": true
        }
    }
}

The new service key now appears in the Megaport Portal.

Editing or disabling the key

You can edit the details of a service key or permanently disable it.

There might be several reasons why you would want to disable the key. For example, you create a service key to one of your Ports and share it with your customer but before your customer creates a connection with the service key, the Port becomes unavailable and you want to prevent your customer from using that service key.

To edit or disable the service key

In Postman, open the Connections folder in the left navigation and select Service Keys > PUT Update Service Key.
Edit the details of the service key as needed.
To permanently disable the service key, set the active parameter to false.

You can share the service key however you prefer, such as email or messaging.

Note

The recipient of the service key cannot alter or modify the service key parameters.

Creating a VXC with a service key

After you receive a service key, you can create a VXC with the service key to connect the A-End on-ramp defined in the service key and your B-End on-ramp.

To create a VXC with a service key

In Postman, open the Connections folder in the left navigation and select Service Keys > POST Create VXC with a Service Key.
Specify the configuration details in the Body of the request.
- productUid - Enter the productUid of the Port in your Megaport location.
- bEnd: productUid - Enter the productUid location from the service key lookup.
- serviceKey- Enter the full service key.
- ratelimit - Specify a ratelimit up to the maximum rate limit set on the service key.
- term - Specify the contract term for the VXC. Valid values are 1, 12, 24, and 36 months. If you don’t specify term when ordering a VXC, it defaults to 1 (No Minimum Term).
- shutdown - You can temporarily shut down and re-enable the VXC. Valid values are true (shut down) and false (enabled). If not provided, it defaults to false (enabled).
- promoCode - You can enter a promotional code for the service order. The code is not validated, so if the code doesn’t exist or doesn’t work for the service, the call will still be successful.
- vlan - (Optional) Preferred A-End VLAN. Specify an unused VLAN ID for this connection.
  
  This must be a unique VLAN ID on this Port and can range from 2 to 4093. If you specify a VLAN ID that is already in use, the system displays the next available VLAN number. The VLAN ID must be unique to proceed with the order. If you don’t specify a value, Megaport will assign one.
  
  The B-End VLAN for the provider side termination will be automatically populated based on the service key.
```
{
    "productUid": "7fba50bb-ac35-465b-9b8b-9a6d7335ec7a",
    "associatedVxcs": [
        {
            "productName": "VXC from service key",
            "rateLimit": 100,
            "term": 12,
            "shutdown": false,
            "promoCode": "promox3mnthfree2",
            "serviceKey": "106e38ae-eb59-415f-ac81-526a5299851d",
            "aEnd": {
                "vlan": 2
            },
            "bEnd": {
                "productUid": "8611b645-ea50-46eb-b400-1c2fb858a303"
            }
        }
    ]
}
```
When you are done, click Send to make the request.
```
POST /v3/networkdesign/buy
```
Tip

To test your request before you order and see pricing details, use the /v3/networkdesign/validate endpoint with the same Body configuration.

A successful response passes validation and has a 200 OK status.

{
  "message": "VXC [399f0fd8-8a69-4e15-abdb-537b0cb8a858] created. ",
  "terms": "This data is subject to the Acceptable Use Policy https://www.megaport.com/legal/acceptable-use-policy",
  "data": [
    {
      "createDate": 1610140443499,
      "vxcOrderId": 55791,
      "payerMegaPortId": 74841,
      "nonPayerMegaPortId": 39950,
      "payerMegaPortName": "My LA API Port",
      "nonPayerMegaPortName": "BNE5-01-10G",
      "payerCompanyId": 15,
      "nonPayerCompanyId": 28,
      "payerLocationId": 60,
      "nonPayerLocationId": 44,
      "salesId": null,
      "payerCompanyName": "Megaport Lab",
      "nonPayerCompanyName": "6YS",
      "payerMegaPortNsId": 167551,
      "nonPayerMegaPortNsId": 90147,
      "payerVlanId": 2,
      "nonPayerVlanId": 373,
      "payerInnerVlanId": null,
      "nonPayerInnerVlanId": null,
      "payerApproverName": "Test Name",
      "payerApproverId": 32278,
      "nonPayerApproverName": null,
      "nonPayerApproverId": null,
      "payerApproval": 1610140443263,
      "nonPayerApproval": 1610140443308,
      "fixedTerm": true,
      "duration": 1,
      "rollover": true,
      "serviceName": "from My LA API Port to BNE5-01-10G",
      "payerStatus": "APPROVED",
      "nonPayerStatus": "APPROVED",
      "speed": 100,
      "distanceBand": "ZONE",
      "intercapPath": "",
      "awsId": null,
      "promoCode": null,
      "rateType": "MONTHLY",
      "vxcJTechnicalServiceId": 74842,
      "vxcJTechnicalServiceUid": "399f0fd8-8a69-4e15-abdb-537b0cb8a858",
      "provisionDate": 1610140443232,
      "orderType": "NEW",
      "monthlyDiscountAmount": null,
      "discountMonths": null,
      "amazonDirectConnectConfigDto": null,
      "amsixConnectConfigDto": null,
      "webAirProvItem": null,
      "sdrcProvItem": null,
      "rate": null,
      "setup": null,
      "asn": null,
      "bgpPassword": null,
      "usageAlgorithm": "POST_PAID_HOURLY_SPEED_LONG_HAUL_VXC",
      "costCentre": null,
      "azureServiceKey": null,
      "oracleVirtualCircuitId": null,
      "serviceKey": "106e38ae-eb59-415f-ac81-526a5299851d",
      "connectType": "DEFAULT",
      "payerConfig": {},
      "nonPayerConfig": {},
      "attributeTags": {},
      "fullyApproved": true
    }
  ]
}

After ordering the service key VXC, a notification is sent to the company that you are connecting to, and the receiving company can either accept or reject the key. They cannot alter the key but can request modifications to the service key parameters before accepting it.

The service key VXC will appear in the Megaport Portal for both companies.