MediaValet API

https://docs.mediavalet.com
Admin
MediaValet API is a RESTful service that implements hypermedia for consuming MediaValet data with...
Tokens:3,443
Snippets:27
Trust Score:10
Update:6 months ago
Show doc for...
Tokens:
Raw
### Initiate Auth Code Flow

Source: https://docs.mediavalet.com/

Make this GET request to start the OAuth 2.0 Auth Code Flow. Ensure you replace placeholders with your actual client ID, redirect URI, and a unique state parameter.

```http
GET https://login.mediavalet.com/connect/authorize
?client_id=<client-id>
&response_type=code
&scope=openid api
&redirect_uri=<your-redirect-url>
&state=state-296bc9a0
```

--------------------------------

### POST /connect/token (Resource Owner Password Flow)

Source: https://docs.mediavalet.com/

Requests an access token by providing user credentials directly, primarily for non-interactive authentication.

```APIDOC
## POST /connect/token

### Description
Requests an access token using user credentials. Note: This is discouraged for standard user flows and intended for non-interactive authentication.

### Method
POST

### Endpoint
https://login.mediavalet.com/connect/token?grant_type=password

### Parameters
#### Query Parameters
- **grant_type** (string) - Required - Must be 'password'
- **username** (string) - Required - The user's DAM portal username
- **password** (string) - Required - The user's DAM portal password
- **scope** (string) - Required - The requested scope (e.g., 'api')

### Request Headers
- **Authorization** (string) - Required - Basic auth digest of 'client_id:client_secret'
- **Content-Type** (string) - Required - application/x-www-form-urlencoded

### Response
#### Success Response (200)
- **access_token** (string) - The bearer token for API access
- **expires_in** (integer) - Token expiration time in seconds
- **token_type** (string) - The type of token (Bearer)
- **scope** (string) - The granted scope

#### Response Example
{
  "access_token": "ACCESS_TOKEN_VALUE",
  "expires_in": 3600,
  "token_type": "Bearer",
  "scope": "api"
}
```

--------------------------------

### POST /connect/token (Auth Code Flow)

Source: https://docs.mediavalet.com/

Exchanges an authorization code for an access token after the user has authenticated via the browser.

```APIDOC
## POST /connect/token

### Description
Exchanges an authorization code for an access token to be used for subsequent API requests.

### Method
POST

### Endpoint
https://login.mediavalet.com/connect/token

### Request Body
- **grant_type** (string) - Required - Must be 'authorization_code'
- **code** (string) - Required - The authorization code received from the redirect
- **redirect_uri** (string) - Required - The redirect URI used in the initial request
- **client_id** (string) - Required - Your application client ID
- **client_secret** (string) - Required - Your application client secret

### Response
#### Success Response (200)
- **id_token** (string) - The OIDC ID token
- **access_token** (string) - The bearer token for API access
- **expires_in** (integer) - Token expiration time in seconds
- **token_type** (string) - The type of token (Bearer)

#### Response Example
{
  "id_token": "ID_TOKEN_VALUE",
  "access_token": "ACCESS_TOKEN_VALUE",
  "expires_in": 3600,
  "token_type": "Bearer"
}
```

--------------------------------

### Standard API Response Structure

Source: https://docs.mediavalet.com/

All API responses from MediaValet follow a consistent structure, including API version, metadata, record counts, and the actual payload.

```APIDOC
## Standard API Response Structure

### Description
All responses from the MediaValet API adhere to a uniform structure that contains version information, metadata, record counts, and the requested data payload.

### Response Body Example
```json
{
    "ApiVersion": "1.0.0.0",
    "Meta": {
        "MetaInformation": {},
        "Warnings": [],
        "Errors": [],
        "CreatedOn": "2014-01-01T00:00:00Z"
      },
      "RecordCount": {
        "TotalRecordsFound": 0,
        "StartingRecord": 1,
        "RecordsReturned": 10
      },
      "Payload": {}
}
```

### Response Properties
- **ApiVersion** (string) - The version of the API that processed the request.
- **Meta** (object) - Contains metadata useful for understanding the request and response. Fields may vary depending on the endpoint.
  - **MetaInformation** (object) - Additional meta information.
  - **Warnings** (array) - A list of warnings, if any.
  - **Errors** (array) - A list of errors, if any.
  - **CreatedOn** (string) - The date and time the request was processed.
- **RecordCount** (object) - Contains information about the number of records returned.
  - **TotalRecordsFound** (integer) - The total number of records matching the query.
  - **StartingRecord** (integer) - The index of the first record returned.
  - **RecordsReturned** (integer) - The number of records returned in this response.
- **Payload** (object) - The serialized result of the request. The structure of this object depends on the specific endpoint queried.
```

--------------------------------

### Authorize Endpoint

Source: https://docs.mediavalet.com/

Initiates browser-based OpenID Connect flows, such as the authorization code flow. It authenticates the user and returns tokens or an authorization grant to the client application.

```APIDOC
## GET /connect/authorize

### Description
This endpoint is the starting point for browser-based OpenID Connect flows, like the authorization code flow. It authenticates the user and redirects back to the client application with an authorization grant or tokens.

### Method
GET

### Endpoint
/connect/authorize

### Parameters
#### Query Parameters
- **client_id** (string) - Required - Identifies the client application. Must match the pre-registered value.
- **redirect_uri** (string) - Required - The callback URL where the authorization code or tokens should be sent. Must match the pre-registered value.
- **response_type** (string) - Required - Specifies the desired flow. Can be a combination of `code`, `token`, and `id_token`.
- **scope** (string) - Required - Must include `openid` and `api`. `offline_access` is optional for requesting refresh tokens.
- **state** (string) - Optional - A value used to maintain state between the request and callback.
```

--------------------------------

### API Response Structure

Source: https://docs.mediavalet.com/

All API responses follow a consistent structure including version, metadata, record counts, and the actual payload.

```json
{
    "ApiVersion": "1.0.0.0",
    "Meta": {
        "MetaInformation": {},
        "Warnings": [],
        "Errors": [],
        "CreatedOn": "2014-01-01T00:00:00Z"
      },
      "RecordCount": {
        "TotalRecordsFound": 0,
        "StartingRecord": 1,
        "RecordsReturned": 10
      },
      "Payload": {}
}
```

--------------------------------

### Exchange Code for Tokens (POST)

Source: https://docs.mediavalet.com/

Send a POST request from a secure service to exchange the authorization code for access, refresh, and ID tokens. This request must be form-encoded in the body.

```http
POST https://login.mediavalet.com/connect/token
grant_type=authorization_code
&code=3ed822db0c2409dd1babee5150e8ec71dcf854534214fb3a9361ada778a62ea1
&redirect_uri=<your-redirect-url>
&client_id=<client-id>
&client_secret=<client-secret>
```

--------------------------------

### Resource Owner Password Flow Request

Source: https://docs.mediavalet.com/

Use this POST request for non-interactive authentication by sending username and password. The Authorization header should contain a Basic Auth digest of 'client_id:client_secret'.

```http
POST https://login.mediavalet.com/connect/token?grant_type=password
&username={username}
&password={password}
&scope=api
Content-Type: application/x-www-form-urlencoded
Authorization: Basic TE9MIEdvdCA6IFlvdSA6UCA=
```

--------------------------------

### Receive Authorization Code

Source: https://docs.mediavalet.com/

After user authentication, the identity service redirects to your specified URI with an authorization code. This code is used in the next step to exchange for tokens.

```http
GET https://<your-redirect-url>
?client_id=<client-id>
&code=0357a6f78e400d4039eacfdf3007d5b8d6984c9d92a0175fc5ed6f8cc1cec472
&scope=openid api
&state=state-296bc9a0
```

--------------------------------

### Token Response

Source: https://docs.mediavalet.com/

A successful token exchange returns a JSON object containing the ID token, access token, expiration time, and token type.

```json
{
  "id_token":"ID_TOKEN_VALUE",
  "access_token":"ACCESS_TOKEN_VALUE",
  "expires_in":3600,
  "token_type":"Bearer"
}
```

--------------------------------

### Token Endpoint

Source: https://docs.mediavalet.com/

Returns access tokens, ID tokens, and refresh tokens based on the provided request parameters. It's used in both the authorization code flow (second step) and the refresh token flow.

```APIDOC
## POST /connect/token

### Description
This endpoint issues access tokens, ID tokens, and refresh tokens. It is a crucial part of both the authorization code flow (as the second step) and the refresh token flow.

### Method
POST

### Endpoint
/connect/token

### Parameters
#### Request Body
- **client_id** (string) - Required - Identifies the client application.
- **client_secret** (string) - Required - Used with `client_id` to authenticate the client.
- **code** (string) - Required if `grant_type` is `authorization_code` - The authorization code received from the `/authorize` endpoint. It has a 60-second lifetime.
- **grant_type** (string) - Required - Can be `authorization_code` or `refresh_token`.
- **redirect_uri** (string) - Required if `grant_type` is `authorization_code` - The callback URL that must match the one used to generate the `code`.
- **refresh_token** (string) - Required if `grant_type` is `refresh_token` - A valid refresh token previously issued by this endpoint.

### Response
#### Success Response (200)
- **access_token** (string) - An access token for API requests.
- **expires_in** (integer) - The expiration time of the access token in seconds.
- **refresh_token** (string) - An opaque refresh token, provided if `offline_access` scope was granted.
- **id_token** (string) - An ID token, provided if `openid` scope was granted.
```

--------------------------------

### Refresh Access Token Request

Source: https://docs.mediavalet.com/

Send a POST request to the token endpoint with grant_type set to 'refresh_token' and include your existing refresh token, client ID, and client secret.

```http
POST /connect/token HTTP/1.1
Host: login.mediavalet.com
Content-Type: application/x-www-form-urlencoded
cache-control: no-cache
grant_type=refresh_token&refresh_token=9d03ba84f34
&client_id=<client-id>&client_secret=<client-secret>
```

--------------------------------

### Authorize API Request

Source: https://docs.mediavalet.com/

Include the obtained access token in the Authorization header of your API requests to authenticate them. The token type is 'Bearer'.

```http
Authorization: bearer ACCESS_TOKEN_VALUE
```

--------------------------------

### Refresh Token Usage

Source: https://docs.mediavalet.com/

Use a refresh token to generate new access tokens. This avoids the need to re-enter credentials when an access token expires. Refresh tokens are typically obtained during the initial user authentication.

```APIDOC
## POST /connect/token

### Description
Use this endpoint to obtain new access tokens using a refresh token. This is part of the process to maintain authenticated sessions without frequent re-authentication.

### Method
POST

### Endpoint
https://login.mediavalet.com/connect/token

### Parameters
#### Request Body
- **grant_type** (string) - Required - Must be set to `refresh_token`.
- **refresh_token** (string) - Required - The refresh token obtained from a previous authentication.
- **client_id** (string) - Required - Your application's client ID.
- **client_secret** (string) - Required - Your application's client secret.

### Request Example
```
POST /connect/token HTTP/1.1
Host: login.mediavalet.com
Content-Type: application/x-www-form-urlencoded
cache-control: no-cache

grant_type=refresh_token&refresh_token=9d03ba84f34&client_id=<client-id>&client_secret=<client-secret>
```

### Response
#### Success Response (200)
- **id_token** (string) - The ID token.
- **access_token** (string) - The new access token.
- **refresh_token** (string) - A new refresh token.
- **expires_in** (integer) - The expiration time of the access token in seconds.
- **token_type** (string) - The type of token, typically 'Bearer'.

#### Response Example
```json
{
  "id_token":"ID_TOKEN_VALUE",
  "access_token":"ACCESS_TOKEN_VALUE",
  "refresh_token":"NEW_REFRESH_TOKEN",
  "expires_in":3600,
  "token_type":"Bearer"
}
```
```

--------------------------------

### Resource Owner Password Flow Response

Source: https://docs.mediavalet.com/

A successful response for the Resource Owner Password Flow provides an access token, its expiration, token type, and scope.

```json
{
   "access_token":"ACCESS_TOKEN_VALUE",
   "expires_in":3600,
   "token_type":"Bearer",
   "scope":"api"
}
```

--------------------------------

### Refresh Token Response

Source: https://docs.mediavalet.com/

Upon a successful refresh token request, the API returns new ID, access, and refresh tokens along with their expiration time.

```json
{
  "id_token":"ID_TOKEN_VALUE",
  "access_token":"ACCESS_TOKEN_VALUE",
  "refresh_token":"NEW_REFRESH_TOKEN",
  "expires_in":3600,
  "token_type":"Bearer"
}
```
Tokens:
Raw