Red Hat Summit Red Hat SummitSupportConsoleDevelopersStart a trialContact

Chapter 2. Using the 3scale toolbox

The 3scale toolbox is a Ruby client that enables you to manage 3scale products from the command line.

Important

The 3scale toolbox does not support all API as a Product (APIaaP) features. For more details, see the Known issues in the 3scale Release Notes.

2.1. Installing the toolbox
Copy link

The officially supported method of installing the 3scale toolbox is using the 3scale toolbox container image.

2.1.1. Installing the toolbox container image
Copy link

Prerequisites

Procedure

  1. Log in to the Red Hat container registry: 

    $ docker login registry.redhat.io
Username: ${REGISTRY-SERVICE-ACCOUNT-USERNAME}
Password: ${REGISTRY-SERVICE-ACCOUNT-PASSWORD}
Login Succeeded!
    Copy to Clipboard Toggle word wrap

  2. Pull the toolbox container image: 

    $ docker pull registry.redhat.io/3scale-amp2/toolbox-rhel7:3scale2.7
    Copy to Clipboard Toggle word wrap

  3. Verify the installation: 

    $ docker run registry.redhat.io/3scale-amp2/toolbox-rhel7:3scale2.7 3scale help
    Copy to Clipboard Toggle word wrap

Additional resources

2.1.2. Installing unsupported toolbox versions
Copy link

Procedure

2.2. Using supported toolbox commands
Copy link

Use the 3scale toolbox to manage your API from the command line tool (CLI).

Note

The update command has been deprecated and replaced by the copy command. Red Hat discourages the use of deprecated features.

The following commands are supported: 

COMMANDS
    account              account super command
    activedocs           activedocs super command
    application          application super command
    application-plan     application-plan super command
    copy                 copy super command
    help                 show help
    import               import super command
    method               method super command
    metric               metric super command
    policy-registry      policy-registry super command
    proxy-config         proxy-config super command
    remote               remotes super command
    service              services super command
    update               [DEPRECTATED] update super command

OPTIONS
    -c --config-file=<value>      3scale toolbox configuration file
                                  (default: $HOME/.3scalerc.yaml)
    -h --help                     show help for this command
    -k --insecure                 Proceed and operate even for server
                                  connections otherwise considered insecure
    -v --version                  Prints the version of this command
       --verbose                  Verbose mode
Copy to Clipboard Toggle word wrap

2.3. Importing services
Copy link

Import services from a CSV file by specifying the following fields in this order (you also need to include these headers in your CSV file): 

service_name,endpoint_name,endpoint_http_method,endpoint_path,auth_mode,endpoint_system_name,type
Copy to Clipboard Toggle word wrap

You need the following information:

  • A 3scale admin account: {3SCALE_ADMIN}

  • The domain your 3scale instance is running on: {DOMAIN_NAME}

    • If you are using hosted APICast this is 3scale.net
  • The access key of your account: {ACCESS_KEY}
  • The CSV file of services, for example: examples/import_example.csv

Import the services by running:

Example

$ docker run -v $PWD/examples/import_example.csv:/tmp/import_example.csv registry.redhat.io/3scale-amp2/toolbox-rhel7:3scale2.7 3scale import csv --destination=https://{ACCESS_KEY}@{3SCALE_ADMIN}-admin.{DOMAIN_NAME} --file=/tmp/import_example.csv
Copy to Clipboard Toggle word wrap

This example uses a Docker volume to mount the resource file in the container. It assumes that the file is available in the current $PWD folder.

2.4. Copying services
Copy link

Create a new service based on an existing one from the same account or from another account. When you copy a service, the relevant ActiveDocs are also copied.

You need the following information:

  • The service id you want to copy: {SERVICE_ID}
  • A 3scale admin account: {3SCALE_ADMIN}

  • The domain your 3scale instance is running on: {DOMAIN_NAME}

    • If you are using hosted APICast this is 3scale.net
  • The access key of your account: {ACCESS_KEY}
  • The access key of the destination account if you are copying to a different account: {DEST_KEY}
  • The name for the new service: {NEW_NAME}

Example

$ docker run registry.redhat.io/3scale-amp2/toolbox-rhel7:3scale2.7 3scale copy service {SERVICE_ID} --source=https://{ACCESS_KEY}@{3SCALE_ADMIN}-admin.{DOMAIN_NAME} --destination=https://{DEST_KEY}@{3SCALE_ADMIN}-admin.{DOMAIN_NAME} --target_system_name={NEW_NAME}
Copy to Clipboard Toggle word wrap

Note

If the service to be copied has custom policies, make sure that their respective custom policy definitions already exist in the destination where the service is to be copied. To learn more about copying custom policy definitions check out the Copying a policy registry.

2.5. Copying service settings only
Copy link

You can bulk copy and update the service and proxy settings, metrics, methods, application plans, application plan limits, as well as mapping rules from a service to another existing service.

You need the following information:

  • The service id you want to copy: {SERVICE_ID}
  • The service id of the destination: {DEST_ID}
  • A 3scale admin account: {3SCALE_ADMIN}

  • The domain your 3scale instance is running on: {DOMAIN_NAME}

    • If you are using hosted APICast this is 3scale.net
  • The access key of your account: {ACCESS_KEY}
  • The access key of the destination account: {DEST_KEY}

Additionally, you can use the optional flags:

  • The -f flag to remove existing target service mapping rules before copying.
  • The -r flag to copy only mapping rules to target service.
Note

The update command has been deprecated and replaced by the copy command. The use of deprecated commands is not supported.

The following example command does a bulk update from one service to another existing service:

Example

$ docker run registry.redhat.io/3scale-amp2/toolbox-rhel7:3scale2.7 3scale update [opts] service --source=https://{ACCESS_KEY}@{3SCALE_ADMIN}-admin.{DOMAIN_NAME} --destination=https://{DEST_KEY}@{3SCALE_ADMIN}-admin.{DOMAIN_NAME} {SERVICE_ID} {DEST_ID}
Copy to Clipboard Toggle word wrap

2.6. Importing OpenAPI definitions
Copy link

To create a new service or to update an existing service, use the definitions from a local file or access credentials. If that service name already exists, it will be updated. Conversely, if the service name does not exist, it will be created.

The default service name for the import is taken from info.title in the OpenAPI definition. You can override this service name using --target_system_name=<NEW NAME>. If that service name already exists, it will be updated. Conversely, if the service name does not exist, it will be created.

The following rules apply to every import:

  • Definitions are validated as OpenAPI 2.0.
  • All mapping rules in the 3scale product are deleted.
  • In order to be replaced, all method names must be identical to methods defined in the OpenAPI definition (operation.operationId) by using exact pattern matching.
  • Only methods included in the OpenAPI definition are modified.
  • All methods that were present only in the OpenAPI definition are attached to the Hits metric.

  • All mapping rules from the OpenAPI definition are imported.

    • View these in API > Integration.
Note

While there is no security requirement in swagger specifications, the service is considered as an OpenAPI. Toolbox will add a default_credentials policy, which is also known as an anonymous_policy, if it is not already in the policy chain. The default_credentials policy will be configured with the userkey provided in optional parameter --default-credentials-userkey.

Example

$ docker run registry.redhat.io/3scale-amp2/toolbox-rhel7:3scale2.7 3scale import openapi [opts] --destination=https://{DEST_KEY}@{3SCALE_ADMIN}-admin.{DOMAIN_NAME}
Copy to Clipboard Toggle word wrap

2.6.1. Optional flags
Copy link

-d --destination=<value>
3scale target instance in format: http[s]://<authentication>@3scale_domain.
-t --target_system_name=<value>
Target system name.

2.7. Managing remote access credentials
Copy link

To facilitate work with remote 3scale instances, define in a config file the remote web addresses (URLs) with authentication that you will use for accessing those instances. Refer to them by a short name in any 3scale toolbox command.

The default location for the config file is $HOME/.3scalerc.yaml but you can specify another location using the THREESCALE_CLI_CONFIG environment variable or the --config-file <config_file> option.

You can specify remotes using either an access_token or a provider_key:

  • http[s]://<access_token>@<3scale-instance-domain>
  • http[s]://<provider_key>@<3scale-instance-domain>

2.7.1. Listing remote access credentials
Copy link

3scale remote list [--config-file <config_file>]
Copy to Clipboard Toggle word wrap

Shows the list of existing remotes (name, URL and authentication key).

Example

$ docker run registry.redhat.io/3scale-amp2/toolbox-rhel7:3scale2.7 3scale remote list
instance_a https://example_a.net 123456789
instance_b https://example_b.net 987654321
Copy to Clipboard Toggle word wrap

2.7.2. Adding remote access credentials
Copy link

3scale remote add [--config-file <config_file>] <name> <url>
Copy to Clipboard Toggle word wrap

Adds a remote with short name <name> at <url>.

Example

$ docker run registry.redhat.io/3scale-amp2/toolbox-rhel7:3scale2.7 3scale remote add instance_a https://123456789@example_a.net
Copy to Clipboard Toggle word wrap

2.7.3. Removing remote access credentials
Copy link

3scale remote remove [--config-file <config_file>] <name>
Copy to Clipboard Toggle word wrap

Removes the remote woth short name <name>.

Example

$ docker run registry.redhat.io/3scale-amp2/toolbox-rhel7:3scale2.7 3scale remote remove instance_a
Copy to Clipboard Toggle word wrap

2.7.4. Renaming remote access credentials
Copy link

3scale remote rename [--config-file <config_file>] <old_name> <new_name>
Copy to Clipboard Toggle word wrap

Renames remote with short name <old_name> to <new_name>.

Example

$ docker run registry.redhat.io/3scale-amp2/toolbox-rhel7:3scale2.7 3scale remote rename instance_a instance_b
Copy to Clipboard Toggle word wrap

2.8. Application plans
Copy link

Use the 3scale toolbox to create, update, list, delete, show, or export/import application plans in your Developer Portal.

2.8.1. Creating a new application plan
Copy link

Use the following steps to create a new application plan:

  • You have to provide the application plan name.
  • To override the system-name, use the optional parameter.
  • If an application plan with the same name already exists, you will see an error message.
  • Set as default the application plan by using the --default flag.

  • Create a published application plan by using the --publish flag.

    • By default, it will be hidden.

  • Create a disabled application plan by using the --disabled flag.

    • By default, it will be enabled.
Note

  • The service positional argument is a service reference and can be either service id or service system_name.

    • The toolbox uses either one.

The following command creates a new application plan: 

3scale application-plan create [opts] <remote> <service> <plan-name>
Copy to Clipboard Toggle word wrap

Use the following options while creating application plans: 

Options
       --approval-required=<value>      The application requires approval: true or false
       --cost-per-month=<value>         Cost per month
    -d --default                        This will make the default application plan
       --disabled                       This will disable all methods and metrics in
                                        the application plan
       --end-user-required=<value>      End user required: true or false
    -p --published                      This will publish the application plan
       --setup-fee=<value>              Set-up fee
    -t --system-name=<value>            This will set application plan system name
       --trial-period-days=<value>      The trial period in days

Options for application-plan
    -c --config-file=<value>            3scale toolbox configuration file
                                        (default: $HOME/.3scalerc.yaml)
    -h --help                           show help for this command
    -k --insecure                       Proceed and operate even for server
                                        connections otherwise considered insecure
    -v --version                        This will print the version of this command
       --verbose                        Verbose mode
Copy to Clipboard Toggle word wrap

2.8.2. Creating or updating application plans
Copy link

Use the following steps to create a new application plan if it does not exist, or to update an existing one:

  • Update the default application plan by using the --default flag.
  • Update the published application plan by using the --publish flag.
  • Update the hidden application plan by using the --hide flag.
  • Update the disabled application plan by using the --disabled flag.
  • Update the enabled application plan by using the --enabled flag.
Note

  • The service positional argument is a service reference and can be either service id or service system_name.

    • The toolbox uses either one.

  • The plan positional argument is a plan reference and can be either plan id or plan system_name.

    • The toolbox uses either one.

The following command updates the application plan: 

3scale application-plan create [opts] <remote> <service> <plan>
Copy to Clipboard Toggle word wrap

Use the following options while updating application plans: 

Options
       --approval-required=<value>      The application requires approval: true or false
       --cost-per-month=<value>         Cost per month
       --default                        This will make the default application plan
       --disabled                       This will disable all methods and metrics in
                                        the application plan
       --enabled                        This will enable the application plan
       --end-user-required=<value>      End user required: true or false
       --hide                           This will hide the application plan
    -n --name=<value>                   This will set the plan name
    -p --publish                        This will publish the application plan
       --setup-fee=<value>              Set-up fee
       --trial-period-days=<value>      The trial period in days

Options for application-plan
    -c --config-file=<value>            3scale toolbox configuration file
                                        (default: $HOME/.3scalerc.yaml)
    -h --help                           show help for this command
    -k --insecure                       Proceed and operate even for server
                                        connections otherwise considered
                                        insecure
    -v --version                        This will print the version of this command
       --verbose                        Verbose mode
Copy to Clipboard Toggle word wrap

2.8.3. Listing application plans
Copy link

The following command lists the application plan: 

3scale application-plan list [opts] <remote> <service>
Copy to Clipboard Toggle word wrap

Use the following options while listing application plans: 

Options for application-plan
    -c --config-file=<value>      3scale toolbox configuration file
                                  (default:$HOME/.3scalerc.yaml)
    -h --help                     show help for this command
    -k --insecure                 Proceed and operate even for server
                                  connections otherwise considered insecure
    -v --version                  This will print the version of this command
       --verbose                  Verbose mode
Copy to Clipboard Toggle word wrap

2.8.4. Showing application plans
Copy link

The following command shows the application plan: 

3scale application-plan show [opts] <remote> <service> <plan>
Copy to Clipboard Toggle word wrap

Use the following options while showing application plans: 

Options for application-plan
    -c --config-file=<value>      3scale toolbox configuration file
                                  (default: $HOME/.3scalerc.yaml)
    -h --help                     show help for this command
    -k --insecure                 Proceed and operate even for server
                                  connections otherwise considered insecure
    -v --version                  This will print the version of this command
       --verbose                  Verbose mode
Copy to Clipboard Toggle word wrap

2.8.5. Deleting application plans
Copy link

The following command deletes the application plan: 

3scale application-plan delete [opts] <remote> <service> <plan>
Copy to Clipboard Toggle word wrap

Use the following options while deleting application plans: 

Options for application-plan
    -c --config-file=<value>      3scale toolbox configuration file
                                  (default: $HOME/.3scalerc.yaml)
    -h --help                     show help for this command
    -k --insecure                 Proceed and operate even for server
                                  connections otherwise considered insecure
    -v --version                  This will print the version of this command
       --verbose                  Verbose mode
Copy to Clipboard Toggle word wrap

2.8.6. Export/import application plans
Copy link

You can export or import a single application plan to or from yaml content.

Note the following: * Limits defined in the application plan are included. * Pricing rules defined in the application plan are included. * Metrics/methods referenced by limits and pricing rules are included. * Features defined in the application plan are included. * Service can be referenced by id or system_name. * Application Plan can be referenced by id or system_name.

2.8.6.1. Exporting an application plan to a file
Copy link

The following command exports the application plan: 

3scale application-plan export [opts] <remote> <service_system_name> <plan_system_name>
Copy to Clipboard Toggle word wrap

Example

$ docker run -u root -v $PWD:/tmp registry.redhat.io/3scale-amp2/toolbox-rhel7:3scale2.7 3scale application-plan export --file=/tmp/plan.yaml remote_name service_name plan_name
Copy to Clipboard Toggle word wrap

This example uses a Docker volume to mount the exported file in the container for output to the current $PWD folder.

Note

Specific to the export command:

  • Read only operation on remote service and application plan.

  • Command output can be stdout or file.

    • If not specified by -f option, by default, yaml content will be written on stdout.

Use the following options while exporting application plans: 

Options
    -f --file=<value>             Write to file instead of stdout

Options for application-plan
    -c --config-file=<value>      3scale toolbox configuration file
                                  (default: $HOME/.3scalerc.yaml)
    -h --help                     show help for this command
    -k --insecure                 Proceed and operate even for server
                                  connections otherwise considered insecure
    -v --version                  Prints the version of this command
       --verbose                  Verbose mode
Copy to Clipboard Toggle word wrap

2.8.6.2. Importing an application plan from a file
Copy link

The following command imports the application plan: 

3scale application-plan import [opts] <remote> <service_system_name>
Copy to Clipboard Toggle word wrap

Example

$ docker run -v $PWD/plan.yaml:/tmp/plan.yaml registry.redhat.io/3scale-amp2/toolbox-rhel7:3scale2.7 3scale application-plan import --file=/tmp/plan.yaml remote_name service_name
Copy to Clipboard Toggle word wrap

This example uses a Docker volume to mount the imported file in the container from the current $PWD folder.

2.8.6.3. Importing an application plan from URL
Copy link

3scale application-plan import -f http[s]://domain/resource/path.yaml remote_name service_name
Copy to Clipboard Toggle word wrap
Note

Specific to import command:

  • Command input content can be stdin, file or URL format.

    • If not specified by -f option, by default, yaml content will be read from stdin.
  • If application plan cannot be found in remote service, it will be created.

  • Optional param -p, --plan to override remote target application plan id or system_name.

    • If not specified by -p option, by default, application plan will be referenced by plan attribute system_name from yaml content.
  • Any metric or method from yaml content that cannot be found in remote service, will be created.

Use the following options while importing application plans: 

Options
    -f --file=<value>                  Read from file or url instead of stdin
    -p --plan=<value>                  Override application plan reference

Options for application-plan
    -c --config-file=<value>           3scale toolbox configuration file
                                       (default: $HOME/.3scalerc.yaml)
    -h --help                          show help for this command
    -k --insecure                      Proceed and operate even for server
                                       connections otherwise considered
                                       insecure
    -v --version                       Prints the version of this command
       --verbose                       Verbose mode
Copy to Clipboard Toggle word wrap

2.9. Metrics
Copy link

Use the 3scale toolbox to create, update, list, and delete metrics in your Developer Portal.

2.9.1. Creating metrics
Copy link

Use the following steps for creating metrics:

  • You have to provide the metric name.
  • To override the system-name, use the optional parameter.
  • If metrics with the same name already exist, you will see an error message.

  • Create a disabled metric by using the --disabled flag.

    • By default, it will be enabled.
Note

  • The service positional argument is a service reference and can be either service id or service system_name.

    • The toolbox uses either one.

The following command creates metrics: 

3scale metric create [opts] <remote> <service> <metric-name>
Copy to Clipboard Toggle word wrap

Use the following options while creating metrics: 

Options
       --description=<value>      This will set a metric description
       --disabled                 This will disable this metric in all application plans
    -t --system-name=<value>      This will set the application plan system name
       --unit=<value>             Metric unit: default hit

Option for metric
    -c --config-file=<value>      3scale toolbox configuration file
                                  (default: $HOME/.3scalerc.yaml)
    -h --help                     show help for this command
    -k --insecure                 Proceed and operate even for server
                                  connections otherwise considered insecure
    -v --version                  This will print the version of this command
       --verbose                  Verbose mode
Copy to Clipboard Toggle word wrap

2.9.2. Creating or updating metrics
Copy link

Use the following steps to create new metrics if they do not exist, or to update an existing one:

  • If metrics with the same name already exist, you will see an error message.
  • Update a disabled metric by using the --disabled flag.
  • Update to enabled metric by using the --enabled flag.
Note

  • The service positional argument is a service reference and can be either service id or service system_name.

    • The toolbox uses either one.

  • The metric positional argument is a metric reference and can be either metric id or metric system_name.

    • The toolbox uses either one.

The following commmand updates metrics: 

3scale metric apply [opts] <remote> <service> <metric>
Copy to Clipboard Toggle word wrap

Use the following options while updating metrics: 

Options
       --description=<value>      This will set a metric description
       --disabled                 This will disable this metric in all application plans
       --enabled                  This will enable this metric in all application plans
    -n --name=<value>             This will set the metric name
       --unit=<value>             Metric unit: default hit

Options for metric
    -c --config-file=<value>      3scale toolbox configuration file
                                  (default: $HOME/.3scalerc.yaml)
    -h --help                     show help for this command
    -k --insecure                 Proceed and operate even for server
                                  connections otherwise considered insecure
    -v --version                  This will print the version of this command
       --verbose                  Verbose mode
Copy to Clipboard Toggle word wrap

2.9.3. Listing metrics
Copy link

The following command lists metrics: 

3scale metric list [opts] <remote> <service>
Copy to Clipboard Toggle word wrap

Use the following options while listing metrics: 

Options for metric
    -c --config-file=<value>      3scale toolbox configuration file
                                  (default: $HOME/.3scalerc.yaml)
    -h --help                     show help for this command
    -k --insecure                 Proceed and operate even for server
                                  connections otherwise considered insecure
    -v --version                  This will print the version of this command
       --verbose                  Verbose mode
Copy to Clipboard Toggle word wrap

2.9.4. Deleting metrics
Copy link

The following command deletes metrics: 

3scale metric delete [opts] <remote> <service> <metric>
Copy to Clipboard Toggle word wrap

Use the following options while deleting metrics: 

Options for metric
    -c --config-file=<value>      3scale toolbox configuration file
                                  (default: $HOME/.3scalerc.yaml)
    -h --help                     show help for this command
    -k --insecure                 Proceed and operate even for server
                                  connections otherwise considered insecure
    -v --version                  This will print the version of this command
       --verbose                  Verbose mode
Copy to Clipboard Toggle word wrap

2.10. Methods
Copy link

Use the 3scale toolbox to create, apply, list, and delete methods in your Developer Portal.

2.10.1. Creating methods
Copy link

  • You have to provide the method name.
  • To override the system-name, use the optional parameter.
  • If a method with the same name already exists, you will see an error message.

  • Create a disabled method by --disabled flag.

    • By default, it will be enabled.
Note

  • The service positional argument is a service reference and can be either service id or service system_name.

    • The toolbox uses either one.

The following command creates a method: 

3scale method create [opts] <remote> <service> <method-name>
Copy to Clipboard Toggle word wrap

Use the following options while creating methods: 

Option
       --description=<value>      This will set a method description
       --disabled                 This will disable this method in all
                                  application plans
    -t --system-name=<value>      This will set the method system name

Options for method
    -c --config-file=<value>      3scale toolbox configuration file (default:
                                  $HOME/.3scalerc.yaml)
    -h --help                     show help for this command
    -k --insecure                 Proceed and operate even for server
                                  connections otherwise considered insecure
    -v --version                  This will print the version of this command
       --verbose                  Verbose mode
Copy to Clipboard Toggle word wrap

2.10.2. Creating or updating methods
Copy link

Use the following steps for creating new methods if they do not exist, or to update an existing ones:

  • If a method with the same name already exists, command will fail.
  • Update to disabled method by using --disabled flag.
  • Update to enabled method by using --enabled flag.
Note

  • The service positional argument is a service reference and can be either service id or service system_name.

    • The toolbox uses either one.

  • The method positional argument is a method reference and can be either method id or method system_name.

    • The toolbox uses either one.

The following command updates a method: 

3scale method apply [opts] <remote> <service> <method>
Copy to Clipboard Toggle word wrap

Use the following options while updating methods: 

Options
       --description=<value>      This will set a method description
       --disabled                 This will disable this method in all
                                  application plans
       --enabled                  This will enable this method in all
                                  application plans
    -n --name=<value>             This will set the method name

Options for method
    -c --config-file=<value>      3scale toolbox configuration file
                                  (default: $HOME/.3scalerc.yaml)
    -h --help                     This will show help for this command
    -k --insecure                 Proceed and operate even for server
                                  connections otherwise considered insecure
    -v --version                  This will print the version of this command
       --verbose                  Verbose mode
Copy to Clipboard Toggle word wrap

2.10.3. Listing methods
Copy link

The following command lists methods: 

3scale method list [opts] <remote> <service>
Copy to Clipboard Toggle word wrap

Use the following options while listing methods: 

Options for method
    -c --config-file=<value>      3scale toolbox configuration file
                                  (default: $HOME/.3scalerc.yaml)
    -h --help                     show help for this command
    -k --insecure                 Proceed and operate even for server
                                  connections otherwise considered insecure
    -v --version                  This will print the version of this command
       --verbose                  Verbose mode
Copy to Clipboard Toggle word wrap

2.10.4. Deleting methods
Copy link

The following command deletes methods: 

3scale method delete [opts] <remote> <service> <metric>
Copy to Clipboard Toggle word wrap

Use the following options while deleting methods: 

Options for method
    -c --config-file=<value>      3scale toolbox configuration file
                                  (default: $HOME/.3scalerc.yaml)
    -h --help                     show help for this command
    -k --insecure                 Proceed and operate even for server
                                  connections otherwise considered insecure
    -v --version                  This will print the version of this command
       --verbose                  Verbose mode
Copy to Clipboard Toggle word wrap

2.11. Creating services
Copy link

Use the 3scale toolbox to create, apply, list, show, or delete services in your Developer Portal.

2.11.1. Creating a new service
Copy link

The following command creates a new service: 

3scale service create [options] <remote> <service-name>
Copy to Clipboard Toggle word wrap

Use the following options while creating services: 

Options
    -a --authentication-mode=<value>      Specify authentication mode of the
                                          service ('1' for API key, '2' for
                                          App Id / App Key, 'oauth' for OAuth
                                          mode, 'oidc' for OpenID Connect)
    -d --deployment-mode=<value>          Specify the deployment mode of the
                                          service
       --description=<value>              Specify the description of the
                                          service
    -s --system-name=<value>              Specify the system-name of the
                                          service
       --support-email=<value>            Specify the support email of the
                                          service

Options for service
    -c --config-file=<value>              3scale toolbox configuration file
                                          (default:
                                          $HOME/.3scalerc.yaml)
    -h --help                             show help for this command
    -k --insecure                         Proceed and operate even for server
                                          connections otherwise considered
                                          insecure
    -v --version                          Prints the version of this command
       --verbose                          Verbose mode
Copy to Clipboard Toggle word wrap

2.11.2. Creating or updating services
Copy link

Use the following to create new services if they do not exist, or to update an existing one:

Note

  • service-id_or_system-name positional argument is a service reference.

    • It can be either service id, or service system_name.
    • Toolbox will automatically figure this out.
  • This command is idempotent.

The following command updates services: 

3scale service apply <remote> <service-id_or_system-name>
Copy to Clipboard Toggle word wrap

Use the following options while updating services: 

Options
    -a --authentication-mode=<value>      Specify authentication mode of the
                                          service ('1' for API key, '2' for
                                          App Id / App Key, 'oauth' for OAuth
                                          mode, 'oidc' for OpenID Connect)
    -d --deployment-mode=<value>          Specify the deployment mode of the
                                          service
       --description=<value>              Specify the description of the
                                          service
    -n --name=<value>                     Specify the name of the metric
       --support-email=<value>            Specify the support email of the
                                          service

Options for services
    -c --config-file=<value>              3scale toolbox configuration file
                                          (default: $HOME/.3scalerc.yaml)
    -h --help                             show help for this command
    -k --insecure                         Proceed and operate even for server
                                          connections otherwise considered
                                          insecure
    -v --version                          Prints the version of this command
       --verbose                          Verbose mode
Copy to Clipboard Toggle word wrap

2.11.3. Listing services
Copy link

The following command lists services: 

3scale service list <remote>
Copy to Clipboard Toggle word wrap

Use the following options while listing services: 

Options for services
    -c --config-file=<value>      3scale toolbox configuration file (default:
                                  $HOME/.3scalerc.yaml)
    -h --help                     show help for this command
    -k --insecure                 Proceed and operate even for server
                                  connections otherwise considered insecure
    -v --version                  Prints the version of this command
       --verbose                  Verbose mode
Copy to Clipboard Toggle word wrap

2.11.4. Showing services
Copy link

The following command shows services: 

3scale service show <remote> <service-id_or_system-name>
Copy to Clipboard Toggle word wrap

Use the following options while showing services: 

Options for services
    -c --config-file=<value>      3scale toolbox configuration file
                                  (default: $HOME/.3scalerc.yaml)
    -h --help                     show help for this command
    -k --insecure                 Proceed and operate even for server
                                  connections otherwise considered insecure
    -v --version                  Prints the version of this command
       --verbose                  Verbose mode
Copy to Clipboard Toggle word wrap

2.11.5. Deleting services
Copy link

The following command deletes services: 

3scale service delete <remote> <service-id_or_system-name>
Copy to Clipboard Toggle word wrap

Use the following options while deleting services: 

Options for services
    -c --config-file=<value>      3scale toolbox configuration file (default:
                                  $HOME/.3scalerc.yaml)
    -h --help                     show help for this command
    -k --insecure                 Proceed and operate even for server
                                  connections otherwise considered insecure
    -v --version                  Prints the version of this command
       --verbose                  Verbose mode
Copy to Clipboard Toggle word wrap

2.12. ActiveDocs
Copy link

Use the 3scale toolbox to create, update, list, or delete ActiveDocs in your Developer Portal.

2.12.1. Creating new ActiveDocs
Copy link

To create a new ActiveDocs from your OpenAPI / Swagger compliant API defintion:

  1. Add your API defintion to 3scale, optionally giving it a name: 

    3scale activedocs create <remote> <activedocs-name> <spec>
    Copy to Clipboard Toggle word wrap

    Use the following options while creating ActiveDocs: 

    Options
    -d --description=<value>           Specify the description of the
                                       ActiveDocs
    -i --service-id=<value>            Specify the Service ID associated to
                                       the ActiveDocs
    -p --published                     Specify it to publish the ActiveDoc on
                                       the Developer Portal. Otherwise it
                                       will be hidden
    -s --system-name=<value>           Specify the system-name of the
                                       ActiveDocs
       --skip-swagger-validations      Specify it to skip validation of the
                                       Swagger specification

Options for ActiveDocs
    -c --config-file=<value>           3scale toolbox configuration file
                                       (default: $HOME/.3scalerc.yaml)
    -h --help                          show help for this command
    -k --insecure                      Proceed and operate even for server
                                       connections otherwise considered
                                       insecure
    -v --version                       Prints the version of this command
       --verbose                       Verbose mode
    Copy to Clipboard Toggle word wrap
  2. Publish the definition in your Developer Portal.

2.12.2. Creating or updating ActiveDocs
Copy link

Use the following command to create new ActiveDoc if they do not exist, or to update existing ActiveDocs with a new API definition: 

3scale activedocs apply <remote> <activedocs_id_or_system_name>
Copy to Clipboard Toggle word wrap

Use the following options while updating ActiveDocs: 

Options
    -d --description=<value>           Specify the description of the
                                       ActiveDocs
       --hide                          Specify it to hide the ActiveDocs on
                                       the Developer Portal
    -i --service-id=<value>            Specify the Service ID associated to
                                       the ActiveDocs
       --openapi-spec=<value>          Specify the swagger spec. Can be a
                                       file, an URL or '-' to read from
                                       stdin. This option is mandatory when
                                       applying the ActiveDoc for the first
                                       time
    -p --publish                       Specify it to publish the ActiveDocs
                                       on the Developer Portal. Otherwise it
                                       will be hidden
    -s --name=<value>                  Specify the name of the ActiveDocs
       --skip-swagger-validations      Specify it to skip validation of the
                                       Swagger specification

Options for ActiveDocs
    -c --config-file=<value>           3scale toolbox configuration file
                                       (default: $HOME/.3scalerc.yaml)
    -h --help                          show help for this command
    -k --insecure                      Proceed and operate even for server
                                       connections otherwise considered
                                       insecure
    -v --version                       Prints the version of this command
       --verbose                       Verbose mode
Copy to Clipboard Toggle word wrap

2.12.3. Listing ActiveDocs
Copy link

Use the following command to get information about all ActiveDocs in the developer portal, including:

  • id
  • name
  • system name
  • description
  • published (which means it can be shown in the developer portal)
  • creation date
  • latest updated date

The following command lists all defined ActiveDocs: 

3scale activedocs list <remote>
Copy to Clipboard Toggle word wrap

Use the following options while listing ActiveDocs: 

Options for ActiveDocs
    -c --config-file=<value>      3scale toolbox configuration file
                                  (default: $HOME/.3scalerc.yaml)
    -h --help                     show help for this command
    -k --insecure                 Proceed and operate even for server
                                  connections otherwise considered insecure
    -v --version                  Prints the version of this command
       --verbose                  Verbose mode
Copy to Clipboard Toggle word wrap

2.12.4. Deleting ActiveDocs
Copy link

The following command removes ActiveDocs: 

3scale activedocs delete <remote> <activedocs-id_or-system-name>
Copy to Clipboard Toggle word wrap

Use the following options while deleting ActiveDocs: 

Options for ActiveDocs
    -c --config-file=<value>      3scale toolbox configuration file
                                  (default: $HOME/.3scalerc.yaml)
    -h --help                     show help for this command
    -k --insecure                 Proceed and operate even for server
                                  connections otherwise considered insecure
    -v --version                  Prints the version of this command
       --verbose                  Verbose mode
Copy to Clipboard Toggle word wrap

2.13. Proxy configurations
Copy link

Use the 3scale toolbox to list, show, promote all defined proxy configurations in your Developer Portal.

2.13.1. Listing proxy configuration
Copy link

The following command lists proxy configurations: 

3scale proxy-config list <remote> <service> <environment>
Copy to Clipboard Toggle word wrap

Use the following options while listing proxy configurations: 

Options for proxy-config
    -c --config-file=<value>      3scale toolbox configuration file (default:
                                  /home/msoriano/.3scalerc.yaml)
    -h --help                     show help for this command
    -k --insecure                 Proceed and operate even for server
                                  connections otherwise considered insecure
    -v --version                  Prints the version of this command
       --verbose                  Verbose mode
Copy to Clipboard Toggle word wrap

2.13.2. Showing proxy configurations
Copy link

The following command shows proxy configurations: 

3scale proxy-config show <remote> <service> <environment>
Copy to Clipboard Toggle word wrap

Use the following options while showing proxy configurations: 

Options for proxy-config
    -c --config-file=<value>         3scale toolbox configuration file
                                     (default: /home/msoriano/.3scalerc.yaml)
    -h --help                        show help for this command
    -k --insecure                    Proceed and operate even for server
                                     connections otherwise considered
                                     insecure
    -v --version                     Prints the version of this command
       --verbose                     Verbose mode
Copy to Clipboard Toggle word wrap

2.13.3. Promoting proxy configurations
Copy link

The following command promotes the latest staging proxy configuration to the production environment: 

3scale proxy-config promote <remote> <service>
Copy to Clipboard Toggle word wrap

Use the following options while promoting the latest staging proxy configurations to the production environment: 

Options for proxy-config
    -c --config-file=<value>      3scale toolbox configuration file (default:
                                  /home/msoriano/.3scalerc.yaml)
    -h --help                     show help for this command
    -k --insecure                 Proceed and operate even for server
                                  connections otherwise considered insecure
    -v --version                  Prints the version of this command
       --verbose                  Verbose mode
Copy to Clipboard Toggle word wrap

2.14. Copying a policy registry (custom policies)
Copy link

Use the toolbox command to copy a policy registry from a 3scale source account to a target account when:

  • missing custom policies are being created in target account.
  • matching custom policies are being updated in target account.
  • this copy command is idempotent.
Note
  • Missing custom policies are defined as custom policies that exist in source account and do not exist in an account tenant.
  • Matching custom policies are defined as custom policies that exists in both source and target account.

The following command copies a policy registry: 

3scale policy-registry copy [opts] <source_remote> <target_remote>
Copy to Clipboard Toggle word wrap 
Option for policy-registry
    -c --config-file=<value>      3scale toolbox configuration file (default:
                                  $HOME/.3scalerc.yaml)
    -h --help                     show help for this command
    -k --insecure                 Proceed and operate even for server
                                  connections otherwise considered insecure
    -v --version                  Prints the version of this command
       --verbose                  Verbose mode
Copy to Clipboard Toggle word wrap

2.15. Applications
Copy link

Use the 3scale toolbox to list, create, show, apply, or delete applications Developer Portal.

2.15.1. Listing applications
Copy link

The following command lists applications: 

3scale application list [opts] <remote>
Copy to Clipboard Toggle word wrap

Use the following options while listing applications: 

OPTIONS
       --account=<value>          Filter by account
       --plan=<value>             Filter by application plan.
                                  Service option required.
       --service=<value>          Filter by service
Copy to Clipboard Toggle word wrap

2.15.2. Creating applications
Copy link

Use the create command to create one application linked to a given 3scale account and application plan.

The required positional paramaters are as follows:

  • <service> reference. It can be either service id, or service system_name.

  • <account> reference. It can be one of the following:

    • Account id
    • username, email, or user_id of the admin user of the account
    • provider_key
  • <application plan> reference. It can be either plan id, or plan system_name.
  • <name> application name.

The following command creates applications: 

3scale application create [opts] <remote> <account> <service> <application-plan> <name>
Copy to Clipboard Toggle word wrap

Use the following options while creating applications: 

Options
       --application-id=<value>       App ID or Client ID (for OAuth and
                                      OpenID Connect authentication modes) of
                                      the application to be created.
       --application-key=<value>      App Key(s) or Client Secret (for OAuth
                                      and OpenID Connect authentication
                                      modes) of the application to be
                                      created.
       --description=<value>          Application description
       --redirect-url=<value>         OpenID Connect redirect url
       --user-key=<value>             User Key (API Key) of the application
                                      to be created.
Copy to Clipboard Toggle word wrap

2.15.3. Showing applications
Copy link

The following command shows applications: 

3scale application show [opts] <remote> <application>
Copy to Clipboard Toggle word wrap

Application parameters allow:

  • User_key - API key
  • App_id - from app_id/app_key pair or Client ID for OAuth and OpenID Connect (OIDC) authentication modes
  • Application internal id

2.15.4. Creating or updating applications
Copy link

Use the following command to create new applications if they do not exist, or to update existing applications: 

3scale application apply [opts] <remote> <application>
Copy to Clipboard Toggle word wrap

Application parameters allow:

  • User_key - API key
  • App_id - from app_id/app_key pair or Client ID for OAuth and OIDC authentication modes
  • Application internal id

  • account optional argument is required when application is not found and needs to be created. It can be one of the following:

    • Account id
    • username, email, or user_id of the administrator user of the 3scale account
    • provider_key
  • name cannot be used as unique identifier because application name is not unique in 3scale.
  • Resume a suspended application by --resume flag.
  • Suspends an application - changes the state to suspended by the --suspend flag.

Use the following options while updating applications: 

OPTIONS
       --account=<value>              Application's account. Required when
                                      creating
       --application-key=<value>      App Key(s) or Client Secret (for OAuth
                                      and OpenID Connect authentication
                                      modes) of the application to be
                                      created. Only used when application
                                      does not exist.
       --description=<value>          Application description
       --name=<value>                 Application name
       --plan=<value>                 Application's plan. Required when
                                      creating
       --redirect-url=<value>         OpenID Connect redirect url
       --resume                       Resume a suspended application
       --service=<value>              Application's service. Required when
                                      creating
       --suspend                      Suspends an application (changes the
                                      state to suspended)
       --user-key=<value>             User Key (API Key) of the application
                                      to be created.
Copy to Clipboard Toggle word wrap

2.15.5. Deleting applications
Copy link

The following command deletes an application: 

3scale application delete [opts] <remote> <application>
Copy to Clipboard Toggle word wrap

Application parameters allow:

  • User_key - API key
  • App_id - from app_id/app_key pair or Client ID for OAuth and OIDC authentication modes
  • Application internal id

2.16. Troubleshooting SSL issues
Copy link

This section explains how to resolve issues with Secure Sockets Layer/Transport Layer Security (SSL/TLS).

2.16.1. Installing trusted certificates
Copy link

If you are experiencing issues related to self-signed SSL certificates, you can download and use remote host certificates as described in this section. For example, typical errors include SSL certificate problem: self signed certificate or self signed certificate in certificate chain.

Procedure

  1. Download the remote host certificate using openssl. For example: 

    $ echo | openssl s_client -showcerts -servername self-signed.badssl.com -connect self-signed.badssl.com:443 2>/dev/null | sed -ne '/-BEGIN CERTIFICATE-/,/-END CERTIFICATE-/p' > self-signed-cert.pem
    Copy to Clipboard Toggle word wrap

  2. Ensure that the certificate is working correctly using curl. For example: 

    $ SSL_CERT_FILE=self-signed-cert.pem curl -v https://self-signed.badssl.com
    Copy to Clipboard Toggle word wrap

    If the certificate is working correctly, you will no longer get the SSL error.

  3. Add the SSL_CERT_FILE environment variable to your 3scale commands. For example: 

    $ docker run --env "SSL_CERT_FILE=/tmp/self-signed-cert.pem" -v $PWD/self-signed-cert.pem:/tmp/self-signed-cert.pem egistry.redhat.io/3scale-amp2/toolbox-rhel7:3scale2.7 3scale service list https://{ACCESS_KEY}@{3SCALE_ADMIN}-admin.{DOMAIN_NAME}
    Copy to Clipboard Toggle word wrap

    This example uses a Docker volume to mount the certificate file in the container. It assumes that the file is available in the current $PWD folder.

    An alternative approach would be to create your own toolbox image using the 3scale toolbox image as the base image and then install your own trusted certificate store.

Additional resources

Back to top
Red Hat logoGithubredditYoutubeTwitter

Learn

Try, buy, & sell

Communities

About Red Hat Documentation

We help Red Hat users innovate and achieve their goals with our products and services with content they can trust. Explore our recent updates.

Making open source more inclusive

Red Hat is committed to replacing problematic language in our code, documentation, and web properties. For more details, see the Red Hat Blog.

About Red Hat

We deliver hardened solutions that make it easier for enterprises to work across platforms and environments, from the core datacenter to the network edge.

Theme

© 2025 Red Hat