Authenticating from a CLI

Once you have installed cloudflared you can use Access to authenticate with your identity provider to reach APIs protected by Access.

This process is not meant for configuring a service to run against your API. The token is scoped to your user identity and intended to be used for an end user interacting with an API.

Authenticate CLI Session

Start by running the following command to receive an Access token for a particular application. In this walkthrough, we’ll use “example.com” as a stand-in for a protected API.

cloudflared access token http://example.com

cloudflared will proceed to launch a browser window that contains the same Access login page you find when attempting to reach a web application. Select your identity provider and proceed to login. If the browser window is not launched, you can also use the unique URL output in your command line.

When you have successfully authenticated, the browser will return your token to cloudflared in a cryptographic transfer and store it. The token is valid for the session duration configured by your Access administrator.

Access Your API

Once you have the token, you can proceed to reach your protected API. cloudflared also includes a wrapper for cURL. The wrapper will inject the token into your request a query argument called “token”.

$ cloudflared access curl http://example.com

You can also use the “put” command in cloudflared for any Unix tool to include your token in the request.

Available Commands

login

$ cloudflared access login http://example.com
Initiates the login flow for an application behind Access.

curl

$ cloudflared access curl http://example.com
Wraps curl and includes your token in the request automatically.

token

$ cloudflared access token -app=http://example.com
Retrieves the token scoped to that specific application for use in other command line tools.

Known Limitations

Active Access sessions

If you have an application behind Access that you have already reached from the browser, cloudflared cannot pull the site’s request cookies for security reasons. You must first log out of the application in the browser and use the access login command to initiate a new session from the command line.

FAQ

  • What happens if I attempt to reach an API protected by Access without authenticating?

    cloudflared will publish an error message.

  • What happens if the browser window fails to launch?

    cloudflared also provides the URL in the response that you can visit to authenticate.

  • What about API keys?

    Access sits in front of your API as a method to secure requests to it while allowing your team to authenticate with the identity provider you already use. It does not replace API keys. You can continue to use and manage those if needed.