Manage an API proxy using AMPLIFY CLI
Estimated reading time: 5 minutes
Before you start
- You will need a basic understanding of OAuth authorization (RFC 6749) and JWT (RFC 7523)
- You will need an administrator account for AMPLIFY Central
- Install AMPLIFY CLI:
- Install Node.js 8 LTS or later
- Run the following command:
[sudo] npm install -g @axway/amplify-cli
sudo on Mac OS X or Linux if you do not own the directory that
npm installs packages to. On Windows, you do not need to run as Administrator as
npm installs packages into your AppData directory.
Learn how to authorize your DevOps service to use the AMPLIFY Central DevOps APIs by way of AMPLIFY CLI to manage your API proxies.
- Generate an RSA key pair for your DevOps service account
- Create a DevOps service account in AMPLIFY Central UI
- Authenticate your service account with AMPLIFY platform
- Create a YAML configuration file representing your API proxy
- Create the API proxy using AMPLIFY CLI
- Promote the API proxy using AMPLIFY CLI
- Test the API proxy using AMPLIFY Central UI or a REST client
Service account authentication and authorization
To manage API proxies in AMPLIFY Central, your DevOps service account must authenticate with AMPLIFY platform and it must be authorized to use the AMPLIFY Central DevOps APIs.
To support DevOps service interactions, AMPLIFY Central uses the OAuth 2.0 client credentials flow with JWT:
- Create an RSA public private key pair for your DevOps service account
- Use the public key to register the service account with AMPLIFY platform to obtain a client ID
- Use the client ID and private key to authenticate with AMPLIFY platform to obtain a JWT
- Use the JWT to make authorized API calls to AMPLIFY Central
Generate an RSA key pair
To authorize a DevOps service account with AMPLIFY platform, you need a public and private key pair in RSA format. To create this key pair, use
openssl as follows:
$ openssl genpkey -algorithm RSA -out private_key.pem -pkeyopt rsa_keygen_bits:2048
$ openssl rsa -pubout -in private_key.pem -out public_key.pem
writing RSA key
Create a service account
Log in to AMPLIFY Central UI as an administrator, and create a service account for your DevOps service. Add the public key that you created earlier. When the account is created, copy the client identifier from the Client ID field.
Watch the animation to learn how to do this in AMPLIFY Central UI.
Log in to AMPLIFY CLI
To authorize the service account with AMPLIFY platform, log in to AMPLIFY CLI using the following command:
amplify auth login --secret-file private_key.pem --client-id DOSA_105cf15d051c432c8cd2e1313f54c2da --realm AppcID
Use the private key file that you created earlier, and the client ID from the service account in AMPLIFY Central UI.
Create the API configuration file
The AMPLIFY Central DevOps APIs require a YAML configuration file describing your API (the service you are proxying through AMPLIFY Central) in terms of the API name, base path, Swagger, client authentication, and so on. For example:
apiVersion: v1 # This version ensures backward compatibility and would not mandate a frequent update from a client side
name: 'Musical Instruments' # name of the proxy
basePath: /api/v1 # base path of the proxy
swagger: 'https://ec062a054a2977120b7e721801edb38ca24dfbb3.cloudapp-enterprise.appcelerator.com/apidoc/swagger.json' #swagger url of
type: api-key # type of client authentication policy: can be pass-through or api-key
app: 'Sample App' # optional if policy type is pass-through
tags: ['musical', 'instruments'] # optional
team: # the team which the proxy will be assigned to.
name: 'Default Team'
If you specify
api-key as the authentication policy, you must specify the client
app. If the app does not already exist in AMPLIFY Central, it is created.
It is best to keep the YAML configuration file in the same source control repository as the source code of your service, so that you can update the configuration file when you make changes to the code for your service.
Create an API proxy
create command creates an API proxy if none already exists for this API, or updates the existing API proxy. It returns the name of the API proxy created.
Enter the following command to create an API proxy:
amplify apic create /myservices/my_service_config.yaml
Specify the full path to the YAML configuration file that describes your API.
This command also supports the following options:
The default behavior is to create or update the API proxy. Use this option to force create a new API proxy.
Use this option to specify a path to a local Swagger definition file. This is an alternative to specifying the Swagger definition as a URL in the YAML configuration file.
For details of the API, see Create proxy API.
promote command deploys the latest revision of the API proxy to a target runtime group. It returns the URL of the deployed API proxy and, if you specified API key client authentication, a set of API keys to access the API proxy.
Enter the following command to promote the latest revision of an API proxy to the
amplify apic promote /myservices/my_service_config.yaml "Prod Runtime"
Specify the full path to the YAML configuration file that describes your API and the target runtime group where the API proxy revision is to be deployed.
To promote a specific revision of an API proxy that is already deployed on a runtime group, you can optionally specify a source runtime group. Enter the following command to promote the API proxy revision deployed on
Test Runtime to the
amplify apic promote /myservices/my_service_config.yaml "Test Runtime" "Prod Runtime"
For details of the API, see Promote proxy API.
Test the API proxy
The API proxy is now accessible on the URL returned from the
promote command. You can test the methods and view the results in AMPLIFY Central UI or using a REST client.
To test the API methods in AMPLIFY Central UI, select API Proxies in the left navigation bar, click the appropriate API proxy in the list, and select the Test Methods tab.
You have learned how to authorize your DevOps service to use the AMPLIFY Central DevOps APIs by way of AMPLIFY CLI to manage your API proxies.