> For the complete documentation index, see [llms.txt](https://apidocs.zerionsoftware.com/doc/iformbuilder-v80/llms.txt)

# Create Media Storage Connection

> POST /media_storage/connections
> 
> Stores a connection for the caller's profile, in one of two ways.
> 
> - **Exchange** `{location, code, state}`: exchanges the `code` from the redirect for tokens, which are stored server-side and never returned. The connection is shared across profiles (Box only) exactly when `share: true` was sent to `initiate`: the choice is read from the signed `state`. A `share` sent here is optional and must repeat that choice, or the request answers `400`.
> - **Link** `{location: 3, shared_connection_id}`: links the profile to a shared Box connection listed by `GET /media_storage/connections/shared`. The id must be a shared token of the same provider.
> 
> Either way the profile's previous connection to that provider is replaced. Creating a connection does not change the profile's active media storage location.
> 
> For Dropbox the legacy `ZCCompanyInfo` Dropbox columns are kept in step with the stored connection.
> 
> ### Authorization
> 
> Internal clients only, and a SERVER or COMPANY user. A `state` minted with `share: true` needs a SERVER user here too.



## Servers
- https://api.iformbuilder.com/exzact/api/v80/[servername]: https://api.iformbuilder.com/exzact/api/v80/[servername]


## Authentication methods
- Oauth2


## Parameters
### Headers

- **Authorization** (string)
  e.g. Bearer {access_token}




### Body: application/json (object)

- **location** (integer)

- **code** (string)
  the authorization code from the redirect; required unless `shared_connection_id` is sent

- **state** (string)
  the `state` returned by `initiate`; required with `code`

- **share** (boolean)
  ignored as a choice - sharing is decided by `share` at `initiate` and read from `state`; when sent it must equal that value, or the request answers 400

- **shared_connection_id** (integer)
  Box only; link this shared connection instead of exchanging a code



## Responses
### 201
Created - the connection as `GET` lists it.

#### Body: application/json (object)
- **provider** (string)

- **location** (integer)
  the ZCApiConnector location code (2 Dropbox, 3 Box, 6 OneDrive, 7 SharePoint, 8 Google Drive)

- **active** (boolean)
  whether this is the profile's active media storage location

- **destination_root** (string)
  present only on the active location; a folder path for OneDrive and Dropbox, a library name for SharePoint, a folder id for Box and Google Drive

- **account** (string)
  the provider account's display name, when known


### 400
Bad Request - unsupported `location`; missing `code`; `state` invalid, expired, or minted for another location, profile or server; `share` sent and different from the value `state` was minted with; `shared_connection_id` sent with `code`, `state` or `share`, sent for a location other than 3, or not a linkable id (`Parameter 'shared_connection_id' is invalid`, the same message for an unknown id, a token that is not shared, and a token of another type); or the provider rejected the code.

### 401
Unauthorized - missing or invalid bearer token.

### 403
Forbidden - the client is not an internal client, the token belongs to a BASIC user, or `state` was minted with `share` true and the user is not a SERVER user.

### 502
Bad Gateway - the provider failed or rejected this server's client credentials.

### 503
Service Unavailable - the provider has no OAuth client credentials on this server.


[Powered by Bump.sh](https://bump.sh)
