Detailed API Guide

To use Frontend-only-Authorization (FoAz), 2 things are required:

1. Creating Proxy Config object in Permit.io API
2. Calling FoAz API from your frontend

Creating Proxy Config object in Permit.io API

Proxy Config is a Permit.io API object that contains configuration about your proxied requests. It is used to form a request that will be sent to our Proxy component and eventually will be proxied to your 3rd-party service.

To create a Proxy Config object, you need to send a POST request to the Permit.io API with the following payload properties:

• name - name of the Proxy Config object
• key - key of the Proxy Config object (used to identify the object in Permit.io API)
• mapping_rules - array of mapping rules (see below)
  • url - proxy configuration (see below)
  • method - proxy configuration (see below)
  • resource - proxy configuration (see below)
  • headers - proxy configuration
• jwks - JSON Web Key Set (JWKS) object (see below)
  • keys - array of keys
    • kty - key type
    • kid - key id
    • use - key usage
    • n - modulus
    • e - exponent
• auth_mechanism - The authentication mechanism used to authenticate the user - Bearer or Basic
• secret - The secret that you wish to pass as the Authorization header to your proxied service.

tip

To create the Proxy Config object, send a POST request to the Permit.io API - https://api.permit.io/v2/facts/<Project ID>/<Environment ID>/proxy_configs Look at the API Reference for more details.

Mapping Rules

Mapping rule is a rule that is used to map a request to a resource and action in Permit.io. For example, if you want to map Stripe's Balance POST endpoint to the resource Balance with the action post in Permit.io, the mapping rule would look like this:

{
    "url": "https://api.stripe.com/v1/balance",
    "method": "POST",
    "resource": "balance"
}

Another example will be creating a mapping rule for Stripe's Customers GET endpoint:

{
    "url": "https://api.stripe.com/v1/customers/{customer_id}",
    "method": "GET",
    "resource": "balance"
}

tip

Here you can see that we are using attributes in the URL. These attributes will be replaced with the values from the request that is sent to the Permit.io Proxy component, and will be covered in the Calling FoAz API from your frontend section.

Secret

The secret property is used to pass the secret that you wish to pass as the Authorization header to your proxied service. So if we are using Stripe as an example, the secret would be the Stripe API key.

Example

Continuing the example from the previous section, let's say that we want to send Stripe's Balance and Customers requests directly from our frontend. Our Proxy Config could look like this -

{
    "name": "Stripe Proxy Config",
    "key": "stripe_proxy_config",
    "mapping_rules": [
        {
            "url": "https://api.stripe.com/v1/balance",
            "method": "POST",
            "resource": "balance",
        },
        {
            "url": "https://api.stripe.com/v1/customers/{customer_id}",
            "method": "GET",
            "resource": "customer",
            "headers": {
                "x-permit-example": ""
            }
        }
    ],
    "jwks": {
        "keys": [
            {
                "alg": "RS256",
                "kty": "RSA",
                "use": "sig",
                "n": "****",
                "e": "****",
                "kid": "****",
                "x5t": "****",
                "x5c": [
                    "****"
                ]
            }
        ]
    },
    "auth_mechanism": "Bearer",
    "secret": "<YOUR STRIPE API KEY>"
}

Calling FoAz API from your frontend

After setting up the Proxy Config object in Permit.io API, you can start sending requests from your frontend to the Permit.io Proxy component! To do so, you need to send an HTTP request to the FoAz API.

note

The FoAz API is available at https://proxy.api.permit.io/proxy/<Proxy Config ID>. You can find the Proxy Config ID after creating the Proxy Config object in Permit.io API.

Request

Parameters

The FoAz API supports sending these parameters as part of your request -

• url - required - the URL of the proxied request - for example https://api.stripe.com/v1/customers/customer_123
• tenant - the tenant of the user who sends the request in Permit.io. If not provided, the default tenant will be used.

Methods

The FoAz API supports the following HTTP methods:

• GET
• POST
• PUT
• PATCH
• DELETE

Headers

You can send any headers you wish to the FoAz API as long as it's part of the mapping rule you created in the Proxy Config object. So if you want to send a x-permit-example header, you need to add it to the mapping rule in the Proxy Config object, and then you can send it from your frontend.

Body

The FoAz API supports sending a body in the request.

Response

The FoAz API will return the response from the proxied request, exactly as it was returned from the 3rd-party service.

Example

Continuing the example from the previous section, let's say that we want to send a request to Stripe's Customers endpoint. Our request to the FoAz API would look like this -

const response = await fetch(
    "https://proxy.api.permit.io/proxy/<Proxy Config ID>?url=https://api.stripe.com/v1/customers/customer_123",
    {
        method: "GET",
        headers: {
            "Content-Type": "application/json",
            "x-permit-example": "example",
        },
    }
);

Example using the SDK

You can also use the PermitJS SDK to send requests to the FoAz API. To do so, you need to create a PermitJS client with the proxyId parameter and current user token. This will create a permit proxy client that will send requests to the FoAz API. The SDK proxy client supports the following methods: GET, POST, PUT, PATCH, DELETE

This is an example of how to get SDK proxy client:

import permit from "@permitio/permit-js";
const permitStripeProxy = permit.proxy.getProxy({
    proxyId: "6b120e2ca316430b9f8ea0e1f5ec5555",
    token: userJwt,
});

POST example:

permitStripeProxy
    .post({
        url: "https://stripe.com/createPayment",
        data: { test: "tester" },
        headers: { test: "testHeader" },
    })
    .then((res: any) => {
        console.log("res", res);
    })
    .catch((err: any) => {
        console.log("err", err);
    });

GET example:

permitStripeProxy
    .get({
        url: "https://stripe.com/createPayment",
        params: { test: "tester" },
        headers: { test: "testHeader" },
    })
    .then((res: any) => {
        console.log("res", res);
    })
    .catch((err: any) => {
        console.log("err", err);
    });

When can I start using FoAz ?

The feature is currently only available in early access to a select few.

Subscribe here to get early access.

Join the conversation in our Slack community at the #frontend-only-authz channel.