Quickstart

This page will help you get started with Archetype. You'll be up and running in a jiffy!

Getting Started

Create an Account

Sign upSign up

2. Create an Account

Create an accountCreate an account

Enter your company email, name and create a password to get started!

3. Create an API

Once you create your account and verify your email, on the next page, you can create an API. Enter the name of the API and your company name and then the authentication type.

The authentication type setting refers to where your end users have to pass up their API key to your endpoints to be authorized.

If you select no auth, your API is free to access without an API key and won't require a plan.

URL auth means that your users can add the apikeyfield to the url query:

https://api.uselantern.com/v2/company/list?apikey=d7b6bcf04a8441daae9e0829b36ee791

Body means that we'll expect the apikey is in the request body. In these cases, we recommend against this if you have any secured GET requests.

Header means that we'll expect the apikey is in the request header like standard auth.

The most secure and reliable way you can use the apikey would be sending the request in the header.

If you toggle the "Include a base free tier" button, all users who are registered are initialized with a valid API key with a certain quota.

You can modify the quota limit of the free tier in the Products page. The default limit is set to 1000 API calls a month.

Create an APICreate an API

5. Enter a Redirect and Return URL

Once you've clicked Create, you'll be taken to the settings page. Enter the return and redirect URL fields and then click save to save your changes.

SettingsSettings

For the return and redirect URL, enter any url that is within your domain. Typically, people set the redirect URL to be their users' setting page and the return url to the pricing page.

These urls are set for the checkout session (the page where your users actually enter their credit card details and pay for your API) once they finish their checkout session. The redirect url is for a successful payment processing and return url is for when the user cancels the transaction.

6. Link your Stripe Account

We use Stripe to process payments on your behalf. While you're on the settings page, click on "Connect your stripe account".

Link StripeLink Stripe

This will take you through the flow to link Stripe to Archetype. If you don't already have a Stripe account, no worries, Stripe will walk you through the account creation process.

Once you've successfully linked your Stripe account, it should take you back to the settings page. And then you can get started fully monetizing your API!

7. Create a Product

Now that you've linked your API to your Stripe account, head over to the Product tab.
ProductsProducts

Here you can see a list of all the currently offered products.

Products are all subscription plans that APIs can offer their end user. For more details head over to the Product docs.
Each product has a few features displayed:

  • Product Name: This is the displayed name to your end user
  • Price: This is how much users pay for this plan.
  • Length: This is the duration of the plan. Currently we have the option of setting it as monthly and yearly.
  • Subscribers: This is how many people are currently on this plan (this includes both people in trial and those who have cancelled but their plan has not expired).
  • Quota: If you've set a quota for your plan, this is where you go. Currently it is measured by number of total calls per day.

Products are all subscription plans that APIs can offer their end user. For more details head over to the Product docs.

You can create new products via the Add Product button at the top right and edit/delete a current product with the 3 dots button on the far right of each product.

Once you've clicked Add Product you'll be taken to the edit product page. Edit ProductEdit Product
Here you need to edit the name, description, price, billing period and trial option.

If the usage is metered, that means that you can set a daily quota. If not, access will be unlimited. Best for the top tiers.

If you also want to add a free trial, we offer the ability to set a trial based on number of days/weeks/months.

Once you're done modifying the product, you can hit Save and it'll add the product to your API immediately and that'll be reflected everywhere.

When you delete a product, it is removed from the available products list. There's some specific extra behavior that we cover in the product docs.

8. Add your Endpoints

By default, any endpoint that is in your domain and not registered will allow full unrestricted access even to those who DON'T have a valid API key. This way all your endpoints are safely still accessible.

Once you do add an endpoint to the Endpoint Page, it'll automatically be tied to Archetype's authorization protocol and count against user's quota.

Add EndpointAdd Endpoint

Once you select Add New Endpoint you get taken to the edit endpoint page. Here you enter the

  • Name: Name of the endpoint
  • Description: Description of what the endpoint does
  • Methods: Methods that your endpoint works with
  • Path: The path to the endpoint. You don't need the full url to the endpoint, only the path For example:
    * uselantern.com/api/v1/companies/AAPL is entered as /api/v1/companies/AAPL

Then click Create to actually register that endpoint.

Right now all endpoints are valued at 1 API call for each query but we'll soon be allowing dynamic endpoint values

Add EndpointAdd Endpoint

9. Integrate Archetype into your backend

We integrate with several backends right now but we'll be adding support as we develop them. The guides for each backend are linked as follows:

  1. Python WSGI
    This is for backends in Python built in Django, Flask or Bottle services.
  2. Python Lambda
    This is for backend services using AWS Lambda with Python. It's the easiest integration

10. Integrate Archetype into your frontend

The final step for a fully configured Archetype experience is integrating our process to create a pricing page that routes to checkout sessions where your users subscribe to your different offerings.

Right now the checkout session handles subscriptions and will automatically update your users statuses, like updated quotas, tiers and endpoint access privileges.

You can do this in one of two ways:

  1. Our Javascript SDK
    • It's an out of the box embeddable solution that renders your pricing page and handles the entire checkout flow.
  2. Custom Solution
    • You can handle all the rendering and create your own custom pricing/plan page and use a multi-step process with our REST endpoints to create checkout sessions. This is best for established companies with an existing workflow.

Before you continue, have a look at our page on Checkout Sessions and make sure your configuration is set up.

Custom

If you have an existing workflow or a design theme you really want to follow for your pricing page, this process is for you!

This process is fairly straightforward :

  1. Render a list of all the currently available products.

    Create a GET request with your Public Key to https://api.archetype.dev/public/v1/api/{YOUR_PUBLIC_KEY}/tiers

    This returns a JSON list of products that are currently publicly available. Each object will be formatted like below

[
    {  
        "name": "Basic", 
        "description": "Basic Description", 
        "has_full_access": true, 
        "has_quota": true, 
        "has_trial": false, 
        "is_free": false,
        "period": "month", 
        "price": 40.0, 
        "quota": 1000, 
        "tier_id": "prod_KqVFQR9chN5jB0", 
        "trial_length": 1, 
        "trial_time_frame": "month" 
    }
    ...
]

With this you'll be able to get all the relevant details like the price, quota, trial length and features.

When a user is ready to subscribe to a tier, you'll need the tier_id for the specific product to create a checkout session for the next step.

  1. Create a custom checkout session when a user clicks "subscribe" or tries to sign up for a plan.

You need to create a POST request to:

https://api.archetype.dev/public/v1/api/create-checkout-session

and add these to the body:

{
    "uid": "CURRENT_USER_UID",
    "tier_id": "SUBSCRIBING_TIER_ID"
}

This request will return the below checkout session url.
Redirect your user to the newly generated checkout session url. This will take them through the flow and once the user completes or cancels the flow, it'll take them to the return url or redirect url you set in your API settings.

{
    "url": "CHECKOUT_SESSION_URL"
}

Once they've completed the checkout session, they'll be redirected to the url you set for the redirect_url in your settings page.

Notes

  • The uid will be whatever unique identifier you've set for each user. This needs to be static and unchanging.

  • If the user has not been previously registered before, we'll automatically create a new user with the default parameters.

        Check out our [Users](https://docs.archetype.dev/docs/users)  page for more details. 
    
  • Checkout sessions are ephemeral so you'll always have to create a new checkout session. Do not try to cache a checkout session for each user.

  • These are for currently signed in users, default behavior for non-signed in users should be to take them to your signup flow and keep their planned tier in your session to direct them.

Javascript/React SDK

Import our out-of-the-box soln.

Pass in your public key and deploy and that's it! It'll look something like this:

If you want to customize the layout/styling, check out our Frontend Pricing SDK page.

Sample Apps

To download more complete examples of integrating the Archetype SDK, head over to our sample API resources.

View Samples

Next Steps


Did this page help you?