# Auth API

# 
![REST API logo](../../resources/rest-api-cloud-logo.png)

<hr/>


Version: v3.2.1.1
License: proprietary

## Servers

Production server
```
https://auth.yellowdogsoftware.com
```

## Download OpenAPI description

[Auth API](https://developer.yellowdogsoftware.com/_bundle/rest/auth/api.yaml)

## Authentication Tokens

The Yellow Dog Auth API allows developers to generate 
[JWT](https://jwt.io/) authentication tokens
for access to protected services such as
[the Fetch API](../fetch/api)
and other future services.


**Two Kinds of Tokens**

There are two kinds of token issued by this Auth API:
1. __Access Token__ -- A short lived [JWT](https://jwt.io/) bearer token that provides \
access to services such as [Fetch API](../fetch/api) endpoints. \
The lifespan of these \tokens is measured in minutes, typically 60 minutes.
1. __Refresh Token__ -- A longer lived, single use, [UUID/GUID](https://en.wikipedia.org/wiki/Universally_unique_identifier) that can be
exchanged for a fresh new pair of Access and Refresh Tokens. The lifespan of
a Refresh Token is measured in days, typically 30 days.


**Token Generation Input Credendials**

If you have a valid Refresh Token, you can use it with the
[POST /refreshtoken](./api/authentication-tokens/get-refreshtoken)
endpoint to obtain a new pair of Access and Refresh Tokens.

If you don't have a valid Access or Refresh Token, you can obtain both by submitting
primary credentials consisting of a username, password, and client ID to the
[POST /token](./api/authentication-tokens/get-token)
endpoint of the Auth API.
Once you have a valid Refresh Token, you can use it on a system that is exposed to
external traffic without having to store your primary credentials there.
Since a Refresh Token can only be used once before it expires, an unexpectedly invalid
Refresh Token indicates that the exposed system was likely compromised.
You can recover by generating new tokens from your primary credentials in a protected
environment while separately escalating the security breach.


### Get token via credential

 - [POST /token](https://developer.yellowdogsoftware.com/rest/auth/api/authentication-tokens/get-token.md)

### Get token via refresh token

 - [POST /refreshToken](https://developer.yellowdogsoftware.com/rest/auth/api/authentication-tokens/get-refreshtoken.md)