> ## Documentation Index
> Fetch the complete documentation index at: https://docs.megaport.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Creating a Service Key with the API
> This help topic describes how to create a service key using APIs.
export const topic_0 = "service key"
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](/marketplace/service-keys) and [Managing service keys](/deployment/csp-integration#managing-service-keys). For more information about service key APIs, see [Service Keys (API Documentation)](https://dev.megaport.com/#eb681bb1-1149-4d24-bcc5-b3ac88791022).
## Prerequisites
Before you create a { topic_0 }, ensure that you have:
* Access to the Megaport Portal.
* A Port, MCR, MVE, or NAT Gateway on the Megaport network.
- A valid access token. For more information, see [Creating an API Key](/api/api-key).
**To get the productUid for the Port**
1. In Postman, click **Product Details** in the left navigation and select **GET Product List**.
2. Click **Send**.
3. 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:
```text theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
"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**
1. In Postman, click **Connections** in the left navigation and select **Service Keys > POST Generate Service Key**.
2. 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`.
```json {2} theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
{
"productUid": "8611b645-ea50-46eb-b400-1c2fb858a303",
"description": "Documentation Service Key - Single Use",
"active": true,
"singleUse": true,
"maxSpeed": "500",
"preApproved": true,
"vlan": 3,
"validFor": {
"start": 1608506197135,
"end": 1612015200000
}
}
```
3. 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/](https://www.epochconverter.com/) or [https://it-tools.tech/date-converter](https://it-tools.tech/date-converter) to determine the correct value to enter.
For single-use keys only, specify a VLAN ID (`vlan`) or set `vlan` to `-1` to create an untagged VXC.
You can create a single-use untagged service key only if no untagged connections already exist on the relevant MVE vNIC or Port.
This is the VLAN ID for the B-End. If you have specified a VLAN ID, 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 about VLAN IDs, see [Managing VLAN IDs](/deployment/csp-integration#managing-vlans).
4. When you are done, click **Send** to make the request.
```http theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
POST /v2/service/key
```
A successful response passes validation and has a 200 OK status.
```json {5} theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
{
"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**
1. In Postman, open the **Connections** folder in the left navigation and select **Service Keys > PUT Update Service Key**.
2. Edit the details of the service key as required.
3. To permanently disable the service key, set the `active` parameter to `false`.
## Sharing the key
You can share the service key however you prefer, such as email or messaging.
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**
1. In Postman, open the **Connections** folder in the left navigation and select **Service Keys > POST Create VXC with a Service Key**.
2. 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, 36, 48, and 60 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.
```json theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
{
"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"
}
}
]
}
```
3. When you are done, click **Send** to make the request.
```http theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
POST /v3/networkdesign/buy
```
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.
```json theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
{
"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.