1. Home
    2. Prisma
    3. Prisma Cloud
    4. Prisma Cloud Microsegmentation Administrator's Guide
    5. Microsegmentation Console API
    6. Overview

    Overview

    Object types

    The Microsegmentation Console API accepts and returns JSON or MessagePack encoded objects. This is controlled by the Accept and Content-Type HTTP headers.

    Authentication and authorization

    Most of the resources require authentication and authorization.
    • For a request to be authenticated, it must provide the Authorization HTTP header.
    • For a request to be authorized, a policy must be in place to grant you access.

    Errors

    When an error occurs, either due to the user input or platform error, it is returned as list of errors. Errors always have the same structure:
    • title: The title of the error
    • description: A more detailed description of the error
    • code: The status code of the error
    • trace: Trace ID that can help Palo Alto Networks engineers trace the cause of the error.
    • data: Additional opaque data related to the error.
    For example:
    [
  {
    "code": 422,
    "data": {
      "attribute": "name"
    },
    "description": "Attribute 'name' is required",
    "subject": "elemental",
    "title": "Validation Error",
    "trace": "4da0331d645697d6"
  }
]
    The error codes follow the HTTP status codes:
    There may be additional error codes in certain circumstances. Please refer to the HTTP error code documentation for more information.

    Authentication

    All API calls must explicitly pass the Authorization HTTP header in the following form:
    Authorization: Bearer <token>
    The token is a JSON Web Token (JWT) that can be exchanged from one of the supported authentication sources:
    • Microsegmentation account: username and password.
    • App credentials: X.509 certificate.
    • User-configured OIDC provider.
    • User-configured LDAP server.
    These various sources are called realms.
    Regardless of the realm, the Microsegmentation Console validates the user-provided information and converts identification bits into claims that are inserted in the JWT.
    Administrators can then write API authorizations based on these claims to authorize actions on various parts of the system.
    Generally speaking, you need to call the /issue API in order to get a token.
    curl https://api.console.aporeto.com/issue \
  -X POST \
  -H 'Content-Type: application/json' \
  -d '{
    "realm": "<realm>",
    "validity: "24h",
    "quota": 0,
    "metadata": {<realm-specific-identification>}
  }'
    The realm property can be one of:
    The validity property controls how long the token will be valid. It is expressed in the Golang duration format, like 10s, 6h or 24h. By default, if you omit this value or set it to 0, the validity will be 24h.
    The quota controls how many times a token can be used. Not setting this value or setting it to 0 disables quota so the token can be used as much as you like during its validity period.
    The metadata attribute contains various realm-dependent information (see below).
    Upon correct authentication, the Microsegmentation Console returns a JWT wrapped in a JSON or MessagePack object.
    {
    "quota": 0,
    "realm": "Vince",
    "token": "<jwt>",
    "validity": "24h"
}
    The token attribute contains the actual JWT you need to pass into the Authorization HTTP header for every subsequent request.

    Authenticating with a Microsegmentation account

    To authenticate from your Microsegmentation account, you can issue the following command.
    curl https://api.console.aporeto.com/issue \
  -X POST \
  -H 'Content-Type: application/json' \
  -d '{
    "realm": "Vince",
    "metadata": {
      "vinceAccount": "<account-name>",
      "vincePassword": "<account-password>"
    }
  }'

    Authenticating with an X.509 certificate

    How to retrieve an X.509 certificate from the Microsegmentation Console is not in the scope of this document.
    To use an X.509 user certificate, you must configure your client to pass it on the TLS layer.
    Assuming your certificate (containing the key) is at ~/aporeto.pem, you can retrieve a token by issuing the following command:
    curl https://api.console.aporeto.com/issue \
  -X POST \
  -E "~/aporeto.pem" \
  -H 'Content-Type: application/json' \
  -d '{"realm": "Certificate"}'

    Namespace

    Most of the resources in Microsegmentation Console live in a namespace. When you issue a command, in addition to your JWT, you must pass the X-Namespace HTTP header. This tells Microsegmentation Console which namespace the request is targeting and what API authorizations to apply.
    Note that the API authorization associated with your JWT claims will depend on the namespace you target.
    For instance, you may get the permission to list the namespace in /company/ns1:
    curl https://api.console.aporeto.com/namespaces \
  -H 'Content-Type: application/json' \
  -H 'X-Namespace: /company/ns1' \
  -H 'X-Fields: name' \
  -H 'Authorization: Bearer <token>'
    [
  {
    "name": "/company/ns1/myns"
  },
  {
    "name": "/company/ns1/myotherns"
  }
]
    But not in the namespace /company/ns2:
    curl https://api.console.aporeto.com/namespaces \
  -H 'Content-Type: application/json' \
  -H 'X-Namespace: /company/ns2' \
  -H 'X-Fields: name' \
  -H 'Authorization: Bearer <token>'
    [
  {
    "code": 403,
    "title":"Forbidden",
    "description": "You are not allowed to access this resource."
  }
]

    Idempotency

    The Microsegmentation Console API supports idempotency for POST operations. This allows you to safely retry requests that returned a communication error, but actually were honored by the system.
    If you issue two subsequent POST requests with the same idempotency key, the second will return the exact same response as the first one, while it will not have done anything in the system.
    The idempotency key is passed through the HTTP header Idempotency-Key. The value needs to be a unique identifier. UUID are generally widely used.
    For instance, if you issue the following command twice:
    curl https://api.console.aporeto.com/namespaces \
  -X POST \
  -H 'Content-Type: application/json' \
  -H 'X-Namespace: /company' \
  -H 'Authorization: Bearer <token>' \
  -H 'X-Fields: ID' \
  -d '{"name": "test-namespace-2"}'
    The first will return:
    {"ID":"5d2398157ddf1f3519ce6d96"}
    But the second will fail:
    [
  {
    "code":422,
    "title":"Duplicate Key",
    "description":"Another object exists with the same key"
  }
]
    However, if you set the Idempotency-Key header and issue the following request twice:
    curl \
  -X POST \
  -H 'Content-Type: application/json' \
  -H 'X-Namespace: /company' \
  -H 'Idempotency-Key: abcdef1234' \
  -H 'Authorization: Bearer <token>' \
  -H 'X-Fields: ID' \
  -d '{"name": "test-namespace-2"}' \
  https://api.console.aporeto.com/issue
    The first one returns:
    {"ID":"5d2398157ddf1f3519ce6d96"}
    The second one returns:
    {"ID":"5d2398157ddf1f3519ce6d96"}

    CRUD operations

    Hierarchy layout

    The Microsegmentation Console API follows a three-level structure to traverse the hierarchy. For instance, for a hypothetical object parent that can have children who can in turn have grandchildren, the Microsegmentation Console lays out the API URLs as follows:

    Methods

    The Microsegmentation Console API uses standard HTTP methods to perform actions on resources. Not all methods apply to all URLs.
    • GET: Retrieves many or retrieve one.
    • POST: Creates a new resource.
    • PUT: Fully updates an existing resource.
    • DELETE: Deletes an existing resource.
    • HEAD: Works like a GET but it does not return any body.

    Creating resources

    The POST method can be used with the following resource URLs.
    Example:
    curl https://api.console.aporeto.com/namespaces \
  -X POST \
  -H 'Content-Type: application/json' \
  -H 'X-Namespace: /company/ns1' \
  -H 'X-Fields: name' \
  -H 'Authorization: Bearer <token>' \
  -d '{
    "name": "mynamespace"
  }'

    Retrieving resources

    The GET (or HEAD) method can be used with the following resource URLs.
    You can paginate the results using the query parameters page and pageSize. A pageSize or 0 returns the full list of objects.
    Example:
    curl https://api.console.aporeto.com/namespaces?page=2&pageSize=10 \
  -H 'Content-Type: application/json' \
  -H 'X-Namespace: /company/ns1' \
  -H 'Authorization: Bearer <token>'

    Updating resources

    The PUT method can only be used with the PUT /parents/:id resource URL. It updates the parent with the given ID.
    Updating a resource requires you to resend the entire object, not just the parts you want to change. This ensures (especially through the updateTime property) no conflicts should two clients update the same resource at the same time.
    Example:
    curl https://api.console.aporeto.com/namespaces/5d07f89c7ddf1f5e0210582d \
  -X PUT \
  -H 'Content-Type: application/json' \
  -H 'X-Namespace: /company/ns1' \
  -H 'Authorization: Bearer <token>' \
  -d '{
    "ID": "5d07f89c7ddf1f5e0210582d",
    "SSHCA": "",
    "SSHCAEnabled": false,
    "annotations": {},
    "associatedSSHCAID": "",
    "associatedTags": [],
    "createTime": "2019-06-17T20:31:24.681Z",
    "customZoning": false,
    "description": "Hello world",
    "localCA": "",
    "localCAEnabled": false,
    "metadata": [],
    "name": "/company/apps",
    "namespace": "/company",
    "networkAccessPolicyTags" :[],
    "normalizedTags": [
      "$identity=namespace",
      "$name=/company/apps",
      "$namespace=/company",
      "$id=5d07f89c7ddf1f5e0210582d"
    ],
    "protected": false,
    "serviceCertificateValidity": "1h",
    "updateTime": "2019-06-17T20:31:24.681Z",
    "zone": 0,
    "zoning": 0
  }'

    Deleting resources

    The DELETE method can only be used with the DELETE /parents/:id resource URL. It deletes the parent with the given ID.
    Example:
    curl https://api.console.aporeto.com/namespaces/5d07f89c7ddf1f5e0210582d \
  -X DELETE \
  -H 'Content-Type: application/json' \
  -H 'X-Namespace: /company/ns1' \
  -H 'Authorization: Bearer <token>'

    Recommended For You

    Recommended Videos

    Recommended videos not found.

    © 2023 Palo Alto Networks, Inc. All rights reserved.

    Techdocs Logo