Powered by Redocly

Dynamic Monetization APIs (1.0)

Download OpenAPI specification:Download

APIs to perform Dynamic Monetization activity.

Authorization

APIs to manage authorization keys.

Save a producer administration key

Adds or updates a public key which can be used by a producer user to make Dynamic Monetization API requests. Allow 10 minutes for the key to be available to authorize requests.

SecurityAdministrationAccess
Request
Request Body schema: application/json
required

The request payload.

Array
publicKey
string

A public key in PEM format.

id
string

Your identifier for the key. This identifier must be added as a claim in a JWT token signed with the corresponding private key, in order to indicate which public key should be used to verify the JWT is valid.

Responses
200

OK. The request succeeded in its entirety.

400

Bad Request. Check the request for any errors in the input.

401

Unauthorized. Check authentication details.

put/v1.0/administration-keys
Request samples
application/json
[
  • {
    }
]

Delete a producer administration key

Deletes a specified producer administration key. Pass the ID of the key that you want to delete as a path parameter. It may take up to 10 minutes for the key to be fully removed after calling the API.

SecurityAdministrationAccess
Request
path Parameters
keyId
required
string

Public key ID.

Responses
200

OK. The request succeeded in its entirety.

400

Bad Request. Check the request for any errors in the input.

401

Unauthorized. Check authentication details.

403

Forbidden. It is not possible to delete the last administration key. There must always be at least one key present.

404

Resource not found. The requested resource is not available.

delete/v1.0/administration-keys/{keyId}

Save a client key

Adds or updates a public key which can be used by a client user to make Dynamic Monetization API requests. Allow 10 minutes for the key to be available to authorize requests.

SecurityAdministrationAccess
Request
Request Body schema: application/json
required

The request payload.

Array
publicKey
string

A public key in PEM format.

id
string

Your identifier for the key. This identifier must be added as a claim in a JWT token signed with the corresponding private key, in order to indicate which public key should be used to verify the JWT is valid.

Responses
200

OK. The request succeeded in its entirety.

400

Bad Request. Check the request for any errors in the input.

401

Unauthorized. Check authentication details.

put/v1.0/client-keys
Request samples
application/json
[
  • {
    }
]

Delete a client key

Deletes a specified client key. Pass the ID of the key that you want to delete as a path parameter. It may take up to 10 minutes for the key to be fully removed after calling the API.

SecurityAdministrationAccess
Request
path Parameters
keyId
required
string

Public key ID.

Responses
200

OK. The request succeeded in its entirety.

400

Bad Request. Check the request for any errors in the input.

401

Unauthorized. Check authentication details.

404

Resource not found. The requested resource is not available.

delete/v1.0/client-keys/{keyId}

Get a list of public keys

Gets a list of administration and client public keys.

SecurityAdministrationAccess
Request
query Parameters
next
integer >= 0

Enter the next page value returned by the response to the previous GET /public-keys request to get the next batch of public keys.

size
integer [ 1 .. 100 ]

Number of keys to fetch.

Responses
200

OK. The request succeeded in its entirety.

400

Bad Request. Check the request for any errors in the input.

401

Unauthorized. Check authentication details.

get/v1.0/public-keys
Response samples
application/json
{
  • "keys": [
    ],
  • "next": 0
}

Instances

APIs to manage Dynamic Monetization instances, which host the line items belonging to customers.

Get a list of instances

Returns information about instances owned by a producer's customer accounts.
Each customer account may have one or more instances, and each instance serves exactly one customer account.

SecurityAdministrationAccess
Request
query Parameters
next
integer

Enter the next page value returned by the response to the previous GET /instances request to get the next page of instances.

size
string

Enter the number of items to return. (This number of items is not guaranteed.)

accountId
string

Find instances belonging to this account ID. This query parameter must be used in combination with the 'default' query parameter.

default
boolean

Find the default instance for the given account ID. Must be set to 'true'.

Responses
200

List of instances was successfully returned.

400

Bad Request. Check the request for any errors in the input.

401

Unauthorized. Check authentication details.

403

Forbidden. The user is forbidden from performing this operation. Check user permissions.

404

Resource not found. The requested resource is not available.

500

Internal Server Error. There was an internal error processing the request. If you need to contact support, please include the reference number provided in the response.

get/v1.0/instances
Response samples
application/json
{
  • "content": [
    ],
  • "next": 0
}

Create an instance

Creates a new instance. Each customer account may have one or more instances, and each instance serves exactly one customer account.

This method is intended for use if you do not use FlexNet Operations as your back office, so that you can configure your upstream system (e.g. a CRM) to create instances for your accounts.

SecurityAdministrationAccess
Request
Request Body schema: application/json
required
shortName
required
string [ 1 .. 100 ] characters

User-defined name of the instance.

accountId
required
string non-empty

ID of the customer account owning the instance.

Responses
200

Successfully created an instance

400

Bad Request. Check the request for any errors in the input.

401

Unauthorized. Check authentication details.

403

Forbidden. The user is forbidden from performing this operation. Check user permissions.

500

Internal Server Error. There was an internal error processing the request. If you need to contact support, please include the reference number provided in the response.

post/v1.0/instances
Request samples
application/json
{
  • "shortName": "string",
  • "accountId": "string"
}
Response samples
application/json
{
  • "id": "string",
  • "shortName": "string",
  • "accountId": "string",
  • "defaultInstance": true,
  • "created": 0,
  • "modified": 0
}

Get instance by instance ID

Returns information about a specific instance. Pass the instance ID for which you require information as a path parameter.

SecurityAdministrationAccess
Request
path Parameters
instanceId
required
string <uuid>

The UUID of the Dynamic Monetization instance.

Responses
200

The instance was retrieved

401

Unauthorized. Check authentication details.

404

Resource not found. The requested resource is not available.

get/v1.0/instances/{instanceId}
Response samples
application/json
{
  • "id": "string",
  • "shortName": "string",
  • "accountId": "string",
  • "defaultInstance": true,
  • "created": 0,
  • "modified": 0
}

Line Items

APIs to manage line items mapped to an instance.

Get a list of line items

Returns a list of line items mapped to instances owned by a producer's customer accounts.

SecurityAdministrationAccess or ClientAccess
Request
path Parameters
instanceId
required
string <uuid>

The UUID of the Dynamic Monetization instance.

Responses
200

List of line items for the instance ID.

401

Unauthorized. Check authentication details.

404

Resource not found. The requested resource is not available.

500

Internal Server Error. There was an internal error processing the request. If you need to contact support, please include the reference number provided in the response.

get/v1.0/instances/{instanceId}/line-items
Response samples
application/json
[
  • {
    }
]

Map a line item to an instance

Maps a line item to an instance. The first time this API is called, the payload details will be stored, and reported in a GET line-item request. If the line item is already mapped, then the details stored will be entirely replaced.

This method is intended for use if you do not use FlexNet Operations as your back office, so that you can configure your upstream system (e.g. a CRM or back office) to create line items in Dynamic Monetization for your end customers. (If you use FlexNet Operations as your back office, but use this method directly to provision line items that do not exist in FlexNet Operations, then those line items will not be reflected in FlexNet Operations.)

SecurityAdministrationAccess
Request
path Parameters
instanceId
required
string <uuid>

The UUID of the Dynamic Monetization instance.

Request Body schema: application/json
required
activationId
required
string

The activation ID of a line item that should be mapped to the instance.

state
required
string (LineItemState)

The line item state. Valid states are:

  • DEPLOYED
  • INACTIVE
  • OBSOLETE

INACTIVE and OBSOLETE can only be set when the line item already exists.
An OBSOLETE line item cannot be set to INACTIVE or DEPLOYED.

quantity
required
integer <int64> >= 1

The quantity from the line item to map to the instance.

start
required
integer <int64>

Start date and time of the line item in milliseconds since 1970-01-01 00:00.

end
required
integer <int64>

End date and time of the line item in milliseconds since 1970-01-01 00:00.

required
object (Attributes)

The properties that determine how the service will respond to access requests.

Responses
200

Returned when a line item is successfully updated.

201

Returned when a line item is successfully created.

400

Bad Request. Check the request for any errors in the input.

401

Unauthorized. Check authentication details.

403

Forbidden. The user is forbidden from performing this operation. Check user permissions.

500

Internal Server Error. There was an internal error processing the request. If you need to contact support, please include the reference number provided in the response.

put/v1.0/instances/{instanceId}/line-items
Request samples
application/json
{
  • "activationId": "string",
  • "state": "string",
  • "quantity": 1,
  • "start": 0,
  • "end": 0,
  • "attributes": {
    }
}
Response samples
application/json
"string"

Get a specific line item by ID

Returns information about a specific line item. Pass the line item ID for which you require information as a path parameter.

SecurityAdministrationAccess or ClientAccess
Request
path Parameters
instanceId
required
string <uuid>

The UUID of the Dynamic Monetization instance.

lineItemId
required
string

Line item ID. Note: This is also known as the activation ID.

Responses
200

The requested line item was found and returned successfully.

400

Bad Request. Check the request for any errors in the input.

404

Resource not found. The requested resource is not available.

500

Internal Server Error. There was an internal error processing the request. If you need to contact support, please include the reference number provided in the response.

get/v1.0/instances/{instanceId}/line-items/{lineItemId}
Response samples
application/json
{
  • "activationId": "string",
  • "state": "string",
  • "quantity": 1,
  • "start": 0,
  • "end": 0,
  • "used": 0,
  • "attributes": {
    }
}

Delete a line item by its ID

Deletes a line item given its ID.

This method is intended for use if you do not use FlexNet Operations as your back office, so that you can manage line items in Dynamic Monetization for your end customers. (If you use FlexNet Operations as your back office, but use this method directly to remove line items that exist in FlexNet Operations, then those line items' representation in FlexNet Operations will not be affected.)

SecurityAdministrationAccess
Request
path Parameters
instanceId
required
string <uuid>

The UUID of the Dynamic Monetization instance.

lineItemId
required
string

Line item ID. Note: This is also known as the activation ID.

Responses
204

Line item was successfully un-mapped from the instance.

403

Forbidden. Line item must be in an OBSOLETE state before it can be deleted.

404

Line item is either not mapped to the instance, the instance does not exist, or the line item itself does not exist.

delete/v1.0/instances/{instanceId}/line-items/{lineItemId}

Rate Tables

APIs to manage rate tables. Rate tables are used to define the price of items (how many tokens are charged per item).

Get all rate tables

Gets all the rate tables created, whether the effective time of the rate table has been reached or not.

SecurityAdministrationAccess
Responses
200

Rate tables with all their details were successfully returned.

401

Unauthorized. Check authentication details.

500

Internal Server Error. There was an internal error processing the request. If you need to contact support, please include the reference number provided in the response.

get/v1.0/rate-tables
Response samples
application/json
{
  • "created": 0,
  • "effectiveFrom": 0,
  • "series": "string",
  • "version": "string",
  • "items": [
    ]
}

Create a rate table

Creates a new rate table.

SecurityAdministrationAccess
Request
Request Body schema: application/json
effectiveFrom
integer <int64>

Time when the rate table starts to take effect in milliseconds since 1970-01-01 00:00.

series
string

A means of grouping similar rate tables of different versions.

version
string

The version of this rate table.

Array of objects (RateTableItem)

List of rate table items.

Responses
201

Rate table was successfully saved.

400

Bad Request. Check the request for any errors in the input.

401

Unauthorized. Check authentication details.

403

Forbidden. The user is forbidden from performing this operation. Check user permissions.

409

Another rate table with the same version and series exists.

500

Internal Server Error. There was an internal error processing the request. If you need to contact support, please include the reference number provided in the response.

post/v1.0/rate-tables
Request samples
application/json
{
  • "effectiveFrom": 0,
  • "series": "string",
  • "version": "string",
  • "items": [
    ]
}
Response samples
application/json
{
  • "message": "string"
}

Delete a rate table

Deletes a rate table that hasn't come into effect yet.

Note: Rate tables that are already in effect cannot be deleted.

SecurityAdministrationAccess
Request
query Parameters
series
string

The series of the rate table. If not specified, only a rate table with no series would be deleted.

version
required
string

The version of the rate table.

Responses
204

Rate table was successfully deleted.

404

Rate table does not exist.

409

Rate table is already in effect.

delete/v1.0/rate-tables

Sessions

APIs for elastic access within the context of a session.

Request a new session

Creates a new session for elastic access.

SecurityAdministrationAccess or ClientAccess
Request
header Parameters
x-instance-id
string

UUID of the instance to create the session on. Required by requests that use a ClientAccess token.

Request Body schema: application/json
required

The information required in the request payload.

instanceId
required
string <uuid>

UUID of the instance, used while creating a new session.

Responses
200

OK. The request succeeded in its entirety.

400

Bad Request. Check the request for any errors in the input.

401

Unauthorized. Check authentication details.

500

Internal Server Error. The session state will be set to FAILED. To resolve this, the client should initiate a new session. If you need to contact support, please include the reference number provided in the response.

post/v1.0/sessions
Request samples
application/json
{
  • "instanceId": "64d2028c-ae87-4069-a624-66089d957ef9"
}
Response samples
application/json
{
  • "sessionId": "f6567dd8-e069-418e-8893-7d22fcf12459"
}

Fetch IDLE and ACTIVE sessions

Returns up to 100 live sessions, sorted in descending order of creation time.

SecurityAdministrationAccess or ClientAccess
Request
query Parameters
instanceId
required
string <uuid>

Filter sessions based on Instance UUID.

Responses
200

OK. The request succeeded.

400

Bad Request. Check the request for any errors in the input.

401

Unauthorized. Check authentication details.

500

Internal Server Error. There was an internal error processing the request. If you need to contact support, please include the reference number provided in the response.

get/v1.0/sessions
Response samples
application/json
[
  • {
    }
]

Fetch session details

Returns session details for the specified session ID.

SecurityAdministrationAccess or ClientAccess
Request
path Parameters
sessionId
required
string <uuid>

UUID of the session to fetch.

header Parameters
x-instance-id
string

UUID of the instance the session is linked to. Required by requests that use a ClientAccess token.

Responses
200

OK. The request succeeded.

400

Bad Request. Check the request for any errors in the input.

401

Unauthorized. Check authentication details.

404

Resource not found. The requested resource is not available.

500

Internal Server Error. There was an internal error processing the request. If you need to contact support, please include the reference number provided in the response.

get/v1.0/sessions/{sessionId}
Response samples
application/json
{
  • "sessionId": "f6567dd8-e069-418e-8893-7d22fcf12459",
  • "instanceId": "64d2028c-ae87-4069-a624-66089d957ef9",
  • "state": "IDLE",
  • "items": [
    ]
}

Close a session

Closes a specified session for elastic access.

SecurityAdministrationAccess or ClientAccess
Request
path Parameters
sessionId
required
string <uuid>

UUID of the session to be closed.

header Parameters
x-instance-id
string

UUID of the instance the session is linked to. Required by requests that use a ClientAccess token.

Responses
200

OK. The request succeeded in its entirety.

400

Bad Request. Check the request for any errors in the input.

401

Unauthorized. Check authentication details.

404

Resource not found. The requested resource is not available.

409

Resource conflict caused by another request that is using the same session. Try repeating the request; the session usually becomes free soon.

500

Internal Server Error. There was an internal error processing the request. If you need to contact support, please include the reference number provided in the response.

503

API is temporarily unavailable. Try again later.

delete/v1.0/sessions/{sessionId}

Elastic access request in the context of a session

Makes an elastic access request in the context of a session.

SecurityAdministrationAccess or ClientAccess
Request
path Parameters
sessionId
required
string <uuid>

UUID of the session where the access request is being made.

header Parameters
x-instance-id
string

UUID of the instance the session is linked to. Required by requests that use a ClientAccess token.

Request Body schema: application/json
required

The information required in the request payload.

required
object (Requester)

Requester details

rollbackOnDeny
required
boolean

When true, if the request cannot be granted the session will revert to the combination of items it was charging for before the request was made. When false, if the request cannot be granted the session will refund all items it was charging for before the request was made, and the session state will be set to TERMINATED. The amount refunded will be calculated using the time of the denied request up until the end of the period that has been charged for.

required
Array of objects (RequestedItemRequest)

A list of requested items. Provide an empty list to stop using all items.

Responses
200

OK. The request succeeded in its entirety.

400

Bad Request. This error code is returned when the request contained an invalid instance ID or session ID, the instance ID is missing in the query parameter, or for an invalid request payload.

401

Unauthorized. Check authentication details.

403

Forbidden. The operation might be forbidden due to an invalid JWT. If authorization is valid, this code is returned when one or more of the following apply:

  • the session is already in a FAILED or TERMINATED state. To resolve this, the client should initiate a new session.
  • the access request found rate tables but these do not include one or more of the requested items.
  • the available count is not sufficient to grant the request.
404

Resource not found. The requested resource is not available.

500

Internal Server Error. The session state will be set to FAILED. To resolve this, the client should initiate a new session. If you need to contact support, please include the reference number provided in the response.

503

API is temporarily unavailable. Try again later.

put/v1.0/sessions/{sessionId}
Request samples
application/json
{
  • "requester": {
    },
  • "rollbackOnDeny": true,
  • "requestedItems": [
    ]
}
Response samples
application/json
{
  • "requestedItems": [
    ],
  • "requester": {
    },
  • "correlationId": "string"
}

Send heartbeat

Sends a heartbeat for a session to keep it active.

SecurityAdministrationAccess or ClientAccess
Request
path Parameters
sessionId
required
string <uuid>

UUID of the session to keep active.

header Parameters
x-instance-id
string

UUID of the instance the session is linked to. Required by requests that use a ClientAccess token.

Responses
204

OK. The request succeeded.

400

Bad Request. Check the request for any errors in the input.

401

Unauthorized. Check authentication details.

403

Forbidden. The operation might be forbidden due to an invalid JWT. If authorization is valid, this code is returned when the session is already terminated or failed.

404

Resource not found. The requested resource is not available.

409

Resource conflict caused by another request that is using the same session. Try repeating the request; the session usually becomes free soon.

500

Internal Server Error. There was an internal error processing the request. If you need to contact support, please include the reference number provided in the response.

get/v1.0/sessions/{sessionId}/heartbeat

Non-Session Access Request

APIs for elastic access without a session.

Access request for elastic tokens

API to request products, features or other items that will be charged for using elastic tokens.

SecurityAdministrationAccess or ClientAccess
Request
path Parameters
instanceId
required
string <uuid>

The UUID of the Dynamic Monetization instance.

Request Body schema: application/json
required

The information required in the request payload.

required
object (Requester)

Requester details.

required
Array of objects (RequestedItemRequest)

A list of requested items.

Responses
200

OK The request succeeded in its entirety

400

Bad Request. Check the request for any errors in the input.

401

Unauthorized. Check authentication details.

500

Internal Server Error. There was an internal error processing the request. If you need to contact support, please include the reference number provided in the response.

503

API is temporarily unavailable. Try again later.

post/v1.0/instances/{instanceId}/access-request
Request samples
application/json
{
  • "requester": {
    },
  • "requestedItems": [
    ]
}
Response samples
application/json
{
  • "requestedItems": [
    ],
  • "requester": {
    },
  • "correlationId": "string"
}

Configuration

APIs for managing configuration values that control how customers can access and consume line items.

Available values:

  • timezone.tolerant
    • Allows a line item to be used up to 12 hours before its start date (UTC) and up to 12 hours after its end date (UTC), therefore making it tolerant to all time zones.
    • Supported values: true (enabled) and false (disabled).
    • Default: false

All configuration

Returns all configured values. If a configuration has been modified, the response includes the date of modification and the token key ID that was used to change configuration.

SecurityAdministrationAccess
Responses
200

Configuration was successfully returned.

401

Unauthorized. Check authentication details.

403

Forbidden. The user is forbidden from performing this operation. Check user permissions.

500

Internal Server Error. There was an internal error processing the request. If you need to contact support, please include the reference number provided in the response.

get/v1.0/configuration
Response samples
application/json
[
  • {
    }
]

Update configuration

Update one or more configuration values.

SecurityAdministrationAccess
Request
Request Body schema: application/json
Array
name
string

The name of the configuration.

value
string

The value of the configuration.

Responses
200

Configuration was saved successfully.

400

Bad Request. Check the request for any errors in the input.

401

Unauthorized. Check authentication details.

403

Forbidden. The user is forbidden from performing this operation. Check user permissions.

500

Internal Server Error. There was an internal error processing the request. If you need to contact support, please include the reference number provided in the response.

patch/v1.0/configuration
Request samples
application/json
[
  • {
    }
]