# Authentication and Authorization

## Wallet-based Authentication and Authorization

Picket enables Wallet-based authentication and authorization. In exchange for a signature and authorization requirements (e.g token balance requirements), Picket returns a JWT access token. 

The JWT access token can be used to authorize requests to internal or public off-chain APIs. This enables wallet-centric application use-cases such as restricting access to private content and APIs to users who owns a specific token.

## Terminology

### Authentication and Authorization

While often used interchangeably, authentication and authorization represent fundamentally different functions. Below, we compare and contrast the two to show how they protect applications in complementary ways.

### What are authentication and authorization? <a href="#what-are-authentication-and-authorization" id="what-are-authentication-and-authorization"></a>

In simple terms, authentication is the process of verifying who a user is, while authorization is the process of verifying what they have access to.

Comparing these processes to a real-world example, when you go through security in an airport, you show your ID to authenticate your identity. Then, when you arrive at the gate, you present your boarding pass to the flight attendant, so they can authorize you to board your flight and allow access to the plane.

In Picket, authentication is verifying ownership of a wallet, while authorization is optionally verifying ownership of a specific number of a given token.

### Authentication vs. authorization <a href="#authentication-vs-authorization" id="authentication-vs-authorization"></a>

Here's a quick overview of the differences between authentication and authorization:

| **Authentication**                                                  | **Authorization**                                             |
| ------------------------------------------------------------------- | ------------------------------------------------------------- |
| Determines whether users are who they claim to be                   | Determines what users can and cannot access                   |
| Verifies message signature corresponds to the user's wallet address | Verifies whether access is allowed through policies and rules |
| Usually done before authorization                                   | Usually done after successful authentication                  |
| Generally, transmits info through an ID Token                       | Generally, transmits info through an Access Token             |

In short, picket enables you to ensure access to a resource is protected by both authentication and authorization. If a user can't prove their identity, they won't be allowed into a resource. And even if they can prove their identity, if they are not authorized for that resource, they will still be denied access.

## The Auth Endpoint

The `/auth` endpoint always performs authentication of a wallet and can optionally perform authorization by verifying token ownership when supplied with a contract address and a minimum token balance.

## Authenticate wallets and verify token ownership.

<mark style="color:green;">`POST`</mark> `https://picketapi.com/api/v1/auth`

Returns an access token upon successful authentication and token ownership verification.

#### Request Body

| Name                                        | Type   | Description                                                                                                                                                                                                                    |
| ------------------------------------------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| walletAddress                               | String | <p>Wallet address of user to authenticate. Value should be represented as a string.</p><p></p><p>Ex. <code>0xAD5363fF13a1609a89E89C278898B32A038cC015</code></p><p>This string is <strong>not</strong> case sensitive.</p>     |
| signature<mark style="color:red;">\*</mark> |        | A [signed nonce](https://docs.picketapi.com/picket-docs/reference/concepts/signatures) fetched via [`connect`](https://docs.picketapi.com/picket-docs/reference/concepts/signatures). Value should be represented as a string. |
| contractAddress                             | String | Contract address for which to check whether a user has a token from.                                                                                                                                                           |
| minBalance                                  | String | The minimum balance of tokens from the given contractAddress to check if a user holds                                                                                                                                          |
| chain                                       | String | The [blockchain](https://docs.picketapi.com/picket-docs/reference/concepts/supported-blockchains) that should be used for this operation. Defaults to ethereum-mainnet.                                                        |

{% tabs %}
{% tab title="200: OK Returns object with JWT access token, walletAddress and displayName" %}

```javascript
{
    accessToken: "0xAccessToken",
    walletAddress: "0x..abc",
    displayAddress: "noahfradin.eth"
}
```

{% endtab %}
{% endtabs %}