Clients
You can create either a Credentials or OAuth client in Consume, via the control panel UI. This allows you to be able to set settings once, and use the client multiple times in your front-end Twig templates.
You don't have to use clients if you just want to roll your own Guzzle (opens new window) client. Have a look at the Requests docs.
An on-demand client created entirely in Twig cannot perform OAuth setup. Create and connect an OAuth client in the control panel before using it from a template. For a custom provider implementation, see Client Types.
Credentials Client
A Credentials client is used for the more traditional API, where you might authenticate with an API key as a query param, or a HTTP header value. You can think of this as a simple Guzzle (opens new window) client.
There is a single Generic Credentials Client where you can supply:
- URL
- Query String
- Headers
- HTTP Basic Auth
Once created, you'll be able to call the client in your template to make requests with.
{# Fetch the data for the `myClient` client, as configured by the `URL` #}
{% set data = craft.consume.fetchData('myClient') %}
{# Fetch the `/account` endpoint, based off the URL in the client settings #}
{% set data = craft.consume.fetchData('myClient', 'GET', 'account') %}OAuth Client
Similarly, an OAuth Client will provide the same thing - providing you a Guzzle (opens new window) client that's bootstrapped with all the authentication that goes with OAuth without you having to worry about it.
You can either pick from a supported provider, or create your own Generic client.
A Generic client will require:
- Client ID
- Client Secret
- Scopes (depending on your provider)
- Authorization URL
- Token URL
- API URL
Ensure you provide all these details, then click the Connect button to initialize the OAuth handshake to authenticate you with the provider and fetch an access token. This access token will be saved for future requests.
If the provider supports refresh access tokens, Consume will automatically refresh an expired access token. A revoked connection or failed refresh still needs attention: reconnect the client and check its credentials when requests fail.
Once created, you'll be able to call the client in your template to make requests with.
{# Fetch the data for the `myClient` client, as configured by the `URL` #}
{% set data = craft.consume.fetchData('myClient') %}
{# Fetch the `/account` endpoint, based off the URL in the client settings #}
{% set data = craft.consume.fetchData('myClient', 'GET', 'account') %}