
SaaS Registration API v1
Register SaaS applications and customers, and manage their associations.
Overview
This API allows you to specify the following REST resources for Software as a Service (SaaS):
SaaS Resource | Description |
---|---|
application | The ID of your organization’s SaaS application. |
customer | The ID of your customer who will have access to one or more SaaS applications. |
pair | A mapping between a SaaS application and a SaaS customer. |
Here are details for each API object:
Applications represent your organization’s SaaS applications, which are hosted on the Akamai portal. The required members are the
providerApplicationId
and thesurrogateId
. TheproviderApplicationId
is expected to match a value in a given request the identifies the application. It is expected to hold no more than 50 ASCII characters. ThesurrogateId
uniquely identifies this object in the collection. A human readable name for a given application ID can also be specified.Customers represent your organization’s customers of your SaaS applications. The required members are the
providerCustomerId
and thesurrogateId
. TheproviderCustomerId
is expected to match a value in a given request the identifies the customer. It is expected to hold no more than 50 ASCII characters. The surrogateId uniquely identifies this object in the collection. A human readable name for a given customer ID can also be specified.Pairs represent a pair of
providerApplicationId
andproviderCustomerId
values. These objects include asurrogateId
that uniquely identifies them in the collection.
You can define human-readable names for the application and customer IDs.
These SaaS resources are tied to a contract. You need to specify the contract in each API operation.
Each available object has a globally unique ID which is referred to as
the surrogateID
in the API. You specify this ID when you operate on
a specific object.
NOTE: When an operation includes the
surrogateID
for more than one object, the type of object is appended to the beginning of the variable name likeapplicationSurrogateId
orcustomerSurrogateId
.
Get started
Review Get Started with APIs for details on how to set up client tokens to access any Akamai API. These tokens appear as custom hostnames that look like this:
https://akzz-XXXXXXXXXXXXXXXX-XXXXXXXXXXXXXXXX.luna.akamaiapis.net
.To enable this API, choose the API service named SaaS Registration, and set the access level to READ-WRITE.
Input/output formats
Request input (POST/PUT body content)
Various calls may require you to use query arguments or form elements to pass additional content to the API.
Response output
This API uses the JSON, JavaScript Object Notation, response format.
For some operations a specific status code is returned in the response.
Variable values in input/output syntax
Throughout this document, variable values are shown enclosed in braces
({ }
).
Unless otherwise stated, these braces denote that the value is a variable.
Examples
The following examples assume you have obtained an authorization from
Akamai Control Center. You must substitute
any HOST
values with your specific value. Also, you may have to
replace the curl command with syntax specific to your client (e.g.,
egcurl).
The application requires the contract ID be specified in the request’s
URL or you receive a NOT_AUTHORIZED
error. References to CONTRACT
in these operations should be replaced with your specific contract ID.
Example 1: registering a new customer
For this example, you register a SaaS customer with an ID of
newCustId
.
Prerequisite tasks
Before you begin, run the following GET query to verify whether the customer has already been entered into the system. This query returns your entire list of customers.
$ curl HOST/config-saas-registration/v1/customers?contractId=CONTRACT
This query returns a JSON response in the following format:
[
{
"customerName": "custName1",
"providerCustomerId": "custId1",
"surrogateId": 2
},
{
"customerName": "custName2",
"providerCustomerId": "custId2",
"surrogateId": 3
}
]
THE response is a JSON array containing two customer records and includes the specific records in the system.
NOTE: If you try to fetch a record you do not have access to, or that does not exist, the query returns a 404 error similar to the example below.
Query example
$ curl HOST/config-saas-registration/v1/customers/1?contractId=CONTRACT
{
"instance": "HOST/config-saas-registration/v1/customers/1",
"method": "GET",
"status": 404,
"title": "Not Found",
"type": "https://problems.luna-dev.akamaiapis.net/-/resource-impl/forward-origin-error"
}
If the user specifies the correct value, they get the single object.
$ curl HOST/config-saas-registration/v1/customers/2?contractId=CONTRACT
{
"customerName": "custName1",
"providerCustomerId": "custId1",
"surrogateId": 2
}
Continuing with this example, the providerCustomerId
needed is not
listed, so you need to create it.
Create a customerId
Creating a customer ID requires a POST to the collection resource. In
the POST operation you need to specify a customer ID
(providerCustomerId
) and optionally a customer name
(customerName
).
The customerName
specifies the value to display for this
providerCustomerId
in the reports available from the Akamai
portal. The request returns a Location
header for the new record.
$ curl -X POST -d 'providerCustomerId=newCustId&customerName=AutoSoft' HOST/config-saas-registration/v1/customers?contractId=CONTRACT
Another way to verify that the new customer has been added is to fetch the entire list:
$ curl HOST/config-saas-registration/v1/customers?contractId=CONTRACT
[
{
"customerName": "custName1",
"providerCustomerId": "custId1",
"surrogateId": 2
},
{
"customerName": "custName2",
"providerCustomerId": "custId2",
"surrogateId": 3
},
{
"customerName": "AutoSoft",
"providerCustomerId": "newCustId",
"surrogateId": 5
}
]
The new record displays at the end of the list with a surrogateId
of
5
.
Example 2: registering an application
In this example, you register an application with a
providerApplicationId
of appId1
.
Prerequisites
Before you begin, run the following GET query to verify whether the application has already been entered into the system.
NOTE: This query returns your entire list of applications.
$ curl HOST/config-saas-registration/v1/applications?contractId=CONTRACT
The result of this query is an empty array ([ ]
), which means no
applications have been created for this contract.
The providerApplicationId
is not listed, so you need to create it.
Create the applicationId
Creating an providerApplicationId
requires a POST to the collection
resource. In the POST operation you need to specify an application ID
(providerApplicationId
) and optionally an application name
(applicationName
). The applicationName
specifies the value to
display for this providerApplicationId
in the reports available from
the Akamai portal. The request returns a Location
header for the
new record.
$ curl -X POST -d 'providerApplicationId=appId1' HOST/config-saas-registration/v1/applications?contractId=CONTRACT
The Location
header specifies the link to this new object, you can
also see it listed in the GET result to the collection.
$ curl HOST/config-saas-registration/v1/applications?contractId=CONTRACT
[
{
"providerApplicationId": "appId1",
"surrogateId": 0
}
]
Example 3: creating an customer/application pair
In this example, you create a pair by registering, or associating, a
given customer with an application. In this example the customer is
newCustId
and the application is appId1
.
Prerequisites
First, verify whether both the given customer and the application are in the system. See Example 1 and Example 2 for details.
After verifying that the customer and application are in the system, check to see whether a pair for this customer/application combination has already been entered into the system. Run the following GET query against the entire collection return all configured pairs:
$ curl HOST/config-saas-registration/v1/pairs?contractId=CONTRACT
The result is an empty array ([ ]
) which means no pairs have been
created yet for this contract.
Create the pair
So now you have to create a pair by sending a POST request to the
collection resource that specifies the surrogateId
for both the
application and customer. The POST request returns a Location
header
for the new record because it includes the -v
argument, which turns
on verbose logging. Verbose logging displays the Location
header.
NOTE: In the following example, extraneous log output has been removed for brevity.
$ curl -v -X POST -d 'applicationSurrogateId=0&customerSurrogateId=5' HOST/config-saas-registration/v1/pairs?contractId=CONTRACT
...
< HTTP/1.1 201 Created
...
< Location: HOST/config-saas-registration/v1/pairs/0
The Location
header specifies the link to this new object. You can
use this link to view the new record, as shown in the following
example:
$ curl HOST/config-saas-registration/v1/pairs/0?contractId=CONTRACT
{
"applicationSurrogateId": 0,
"customerSurrogateId": 5,
"surrogateId": 0
}
Example 4: deleting a customer
In this example, you need to both delete a customer and remove all traces of the customer from the system, including any associated pairs.
Prerequisites
If the surrogateId
of the record is known it can be used
directly. Otherwise, you must first fetch the entire list:
$ curl HOST/config-saas-registration/v1/customers?contractId=CONTRACT
[
{
"customerName": "custName1",
"providerCustomerId": "custId1",
"surrogateId": 2
},
{
"customerName": "custName2",
"providerCustomerId": "custId2",
"surrogateId": 3
},
{
"customerName": "AutoSoft",
"providerCustomerId": "newCustId",
"surrogateId": 4
}
]
Delete the customer
The new record is at the end of the list, with a surrogateId
of 4
.
You can issue a DELETE request to that ID.
$ curl -X DELETE HOST/config-saas-registration/v1/customers/4?contractId=CONTRACT
This operation deletes the customer, along with any pairs associated with that customer.
Example 5: updating the name of a customer or an application
This example is for an application, however, the update for a customer is virtually identical. If you want to use this operation for a customer, you’ll have to specify the customer endpoint and change the names of the parameters.
For this example, assume the surrogateId
of the application in
question is 0
.
$ curl -X PUT -d 'applicationName=greatApp' HOST/config-saas-registration/v1/applications/0?contractId=CONTRACT
If desired, you can fetch the list again and verify that it was updated:
[
{
"applicationName": "greatApp",
"providerApplicationId": "appId1",
"surrogateId": 0
}
]
Resources
This section provides details on the Network List API’s set of URL operations.
API summary
Operation | Method | Endpoint |
---|---|---|
Application | ||
List Applications | GET | /config-saas-registration/ |
Create a New Application | POST | /config-saas-registration/ |
Get an Application | GET | /config-saas-registration/ |
Remove an Application | DELETE | /config-saas-registration/ |
Modify an Application | PUT | /config-saas-registration/ |
Customers | ||
List Customers | GET | /config-saas-registration/ |
Create a New Customer | POST | /config-saas-registration/ |
Get a Customer | GET | /config-saas-registration/ |
Remove a Customer | DELETE | /config-saas-registration/ |
Modify a Customer | PUT | /config-saas-registration/ |
Pairs | ||
List Pairs | GET | /config-saas-registration/ |
Create a New Pair | POST | /config-saas-registration/ |
Get a Pair | GET | /config-saas-registration/ |
Remove a Pair | DELETE | /config-saas-registration/ |
Modify a Pair | PUT | /config-saas-registration/ |
List applications
List all Applications associated with a given SaaS-provider-customer contract.
GET /config-saas-registration/
Example: /config-saas-registration/
Parameter | Type | Sample | Description |
---|---|---|---|
Required | |||
contractId |
String | A-1234 |
such as A-1234 |
Status 200 application/json
Response:
[
{
"providerApplicationId": "appId1",
"applicationName": "Example application",
"surrogateId": "123"
}
]
Create a new application
Creates a new application and returns its location.
POST /config-saas-registration/
Example: /config-saas-registration/
Content-Type: application/x-www-form-urlencoded
Request:
providerApplicationId=appId1&applicationName=applicationPrettyName
Parameter | Type | Sample | Description |
---|---|---|---|
Required | |||
contractId |
String | A-1234 |
such as A-1234 |
URL-encoded form parameters:
Parameter | Type | Description |
---|---|---|
Required | ||
applicationId |
String | such as appId1 . Deprecated. Use providerApplicationId instead. If both are specified, providerApplicationId is used. |
providerApplicationId |
String | such as appId1 |
Optional | ||
applicationName |
String | such as Example application |
Status 201
Headers:
Location: https://CONSUMERID.luna.akamaiapis.net/config-saas-registration/v1/applications/123
Get an application
Retrieve a specific application.
GET /config-saas-registration/
Example: /config-saas-registration/
Parameter | Type | Sample | Description |
---|---|---|---|
Required | |||
contractId |
String | A-1234 |
such as A-1234 |
surrogateId |
Integer | 123 |
such as 123 |
Status 200 application/json
Response:
{
"providerApplicationId": "appId1",
"applicationName": "Example application",
"surrogateId": "123"
}
Remove an application
Delete a specific application.
DELETE /config-saas-registration/
Example: /config-saas-registration/
Parameter | Type | Sample | Description |
---|---|---|---|
Required | |||
contractId |
String | A-1234 |
such as A-1234 |
surrogateId |
Integer | 123 |
such as 123 |
Status 204
Modify an application
Updates an application and returns its location.
PUT /config-saas-registration/
Example: /config-saas-registration/
Content-Type: application/x-www-form-urlencoded
Request:
providerApplicationId=appId1&applicationName=applicationPrettyName
Parameter | Type | Sample | Description |
---|---|---|---|
Required | |||
contractId |
String | A-1234 |
such as A-1234 |
surrogateId |
Integer | 123 |
such as 123 |
URL-encoded form parameters:
Parameter | Type | Description |
---|---|---|
Required | ||
applicationId |
String | such as appId1 . Deprecated. Use providerApplicationId instead. If both are specified, providerApplicationId is used. |
providerApplicationId |
String | such as appId1 |
Optional | ||
applicationName |
String | such as Example application |
Status 204
Headers:
Location: https://CONSUMERID.luna.akamaiapis.net/config-saas-registration/v1/applications/123
List customers
List all Customers associated with a given SaaS-provider-customer contract.
GET /config-saas-registration/
Example: /config-saas-registration/
Parameter | Type | Sample | Description |
---|---|---|---|
Required | |||
contractId |
String | A-1234 |
such as A-1234 |
Status 200 application/json
Response:
[
{
"providerCustomerId": "custId1",
"customerName": "Example customer",
"surrogateId": "456"
}
]
Create a new customer
Creates a new customer and returns its location.
POST /config-saas-registration/
Example: /config-saas-registration/
Content-Type: customer/x-www-form-urlencoded
Request:
providerCustomerId=custId1&customerName=customerPrettyName
Parameter | Type | Sample | Description |
---|---|---|---|
Required | |||
contractId |
String | A-1234 |
such as A-1234 |
URL-encoded form parameters:
Parameter | Type | Description |
---|---|---|
Required | ||
providerCustomerId |
String | such as custId1 |
customerId |
String | such as custId1 . Deprecated. Use providerCustomerId instead. If both are specified, providerCustomerId is used. |
Optional | ||
customerName |
String | such as Example customer |
Status 201
Headers:
Location: https://CONSUMERID.luna.akamaiapis.net/config-saas-registration/v1/customers/456
Get a customer
Retrieve a specific customer.
GET /config-saas-registration/
Example: /config-saas-registration/
Parameter | Type | Sample | Description |
---|---|---|---|
Required | |||
contractId |
String | A-1234 |
such as A-1234 |
surrogateId |
Integer | 456 |
such as 456 |
Status 200 application/json
Response:
{
"providerCustomerId": "custId1",
"customerName": "Example customer",
"surrogateId": "456"
}
Remove a customer
Delete a specific customer.
DELETE /config-saas-registration/
Example: /config-saas-registration/
Parameter | Type | Sample | Description |
---|---|---|---|
Required | |||
contractId |
String | A-1234 |
such as A-1234 |
surrogateId |
Integer | 456 |
such as 456 |
Status 204
Modify a customer
Updates a customer and returns its location.
PUT /config-saas-registration/
Example: /config-saas-registration/
Content-Type: customer/x-www-form-urlencoded
Request:
providerCustomerId=custId1&customerName=customerPrettyName
Parameter | Type | Sample | Description |
---|---|---|---|
Required | |||
contractId |
String | A-1234 |
such as A-1234 |
surrogateId |
Integer | 456 |
such as 456 |
URL-encoded form parameters:
Parameter | Type | Description |
---|---|---|
Required | ||
customerId |
String | such as custId1 . Deprecated. Use providerCustomerId instead. If both are specified, providerCustomerId is used. |
providerCustomerId |
String | such as custId1 |
Optional | ||
customerName |
String | such as Example customer |
Status 204
Headers:
Location: https://CONSUMERID.luna.akamaiapis.net/config-saas-registration/v1/customers/456
List pairs
List all Pairs associated with a given SaaS-provider-customer contract.
GET /config-saas-registration/
Example: /config-saas-registration/
Parameter | Type | Sample | Description |
---|---|---|---|
Required | |||
contractId |
String | A-1234 |
such as A-1234 |
Status 200 application/json
Response:
[
{
"applicationSurrogateId": 123,
"customerSurrogateId": 456,
"surrogateId": 789
}
]
Create a new pair
Creates a new pair and returns its location.
POST /config-saas-registration/
Example: /config-saas-registration/
Content-Type: customer/x-www-form-urlencoded
Request:
customerSurrogateId=123&applicationSurrogateId=456
Parameter | Type | Sample | Description |
---|---|---|---|
Required | |||
contractId |
String | A-1234 |
such as A-1234 |
URL-encoded form parameters:
Parameter | Type | Description |
---|---|---|
Required | ||
customerSurrogateId |
Number | Integer such as 123 |
applicationSurrogateId |
Number | Integer such as 456 |
Status 201
Headers:
Location: https://CONSUMERID.luna.akamaiapis.net/config-saas-registration/v1/pairs/789
Get a pair
Retrieve a specific pair.
GET /config-saas-registration/
Example: /config-saas-registration/
Parameter | Type | Sample | Description |
---|---|---|---|
Required | |||
contractId |
String | A-1234 |
such as A-1234 |
surrogateId |
Integer | 123 |
such as 123 |
Status 200 application/json
Response:
{
"applicationSurrogateId": 123,
"customerSurrogateId": 456,
"surrogateId": 789
}
Remove a pair
Delete a specific pair.
DELETE /config-saas-registration/
Example: /config-saas-registration/
Parameter | Type | Sample | Description |
---|---|---|---|
Required | |||
contractId |
String | A-1234 |
such as A-1234 |
surrogateId |
Integer | 123 |
such as 123 |
Status 204
Modify a pair
Updates a customer and returns its location.
PUT /config-saas-registration/
Example: /config-saas-registration/
Content-Type: customer/x-www-form-urlencoded
Request:
customerSurrogateId=123&applicationSurrogateId=456
Parameter | Type | Sample | Description |
---|---|---|---|
Required | |||
contractId |
String | A-1234 |
such as A-1234 |
surrogateId |
Integer | 123 |
such as 123 |
URL-encoded form parameters:
Parameter | Type | Description |
---|---|---|
Required | ||
customerSurrogateId |
Number | Integer such as 123 |
applicationSurrogateId |
Number | Integer such as 456 |
Status 204
Headers:
Location: https://CONSUMERID.luna.akamaiapis.net/config-saas-registration/v1/pairs/789
Errors
This section provides details on the API’s error response format, various possible types of error, and the full range of HTTP response codes including success cases.
Error responses
When a non 2XX HTTPS status code is returned, an error JSON such as the following is also returned:
HTTP/1.1 404 Not Found
Content-Type: application/json
Reply Body:
{
"error": {
"type": "https://akamai-api.com/myapp/errors/resource-not-found",
"title": "resource not found",
"detail": "resource 3 was not found in the system.",
"instance": "http://akamai-api.com/myapp/account/12345/msgs/abc",
"httpStatus": 404
}
}
The returned HTTP error code corresponds to the httpStatus
member;
therefore, the caller does not have to query the headers for this
information.
Error types
The following table describes the types of errors that may be returned.
Error Message | Description |
---|---|
INVALID_ARGUMENT |
A failure occurred because of an invalid argument. |
NOT_FOUND |
The operation referenced a resource that could not be found. |
CONFLICT |
The requested operation could not be performed because of a conflict with an existing resource. |
NOT_AUTHORIZED |
You were not authorized to run this operation. This error may occur if you did not specify the contractId . |
BAD_REQUEST |
A failure occurred. Please check your request arguments. |
Response codes
The API responds with the following set of HTTP codes:
Code | Description |
---|---|
200 | OK |
201 | Created |
400 | Bad Request. Please provide all the required parameters. |
403 | User is not authenticated. |
409 | Conflict |
500 | There is a problem processing your request. Please try again later. The details are provided in the response body. |