Brands

These endpoints allow you to manage Brands, and their metadata, in your orgs. With Brands, you can customize the following:

Note: Some of the curl code examples on this page include SSWS API token authentication. However, Okta recommends using scoped OAuth 2.0 and OIDC access tokens to authenticate with Okta management APIs. OAuth 2.0 and OIDC access tokens provide fine-grain control over the bearer's actions on specific endpoints. See Okta API authentication methods.

List all Brands
OAuth 2.0: okta.brands.read

Lists all the brands in your org

Request
query Parameters
expand
Array of strings

Specifies additional metadata to be included in the response

Items Enum: "themes" "domains" "emailDomain"
after
string

The cursor to use for pagination. It is an opaque string that specifies your current location in the list and is obtained from the Link response header. See Pagination.

limit
integer [ 1 .. 200 ]
Default: 20

A limit on the number of objects to return

q
string

Searches the records for matching value

Responses
200

Successfully returned the list of brands

403

Forbidden

429

Too Many Requests

get/api/v1/brands
Request samples 
Response samples 
application/json
[]
Create a Brand
OAuth 2.0: okta.brands.manage
Creates a new brand in your org


Request 
Request Body schema: application/json
name
required
string
The name of the Brand


 
Responses 
201
Successfully created the brand


400
Bad Request


403
Forbidden


409
Could not create the new brand because same name already exist.


429
Too Many Requests


post/api/v1/brands
Request samples 
application/json
{
  • "name": "My Awesome Brand"
}
Response samples 
application/json
{}
Retrieve a Brand
OAuth 2.0: okta.brands.read
Retrieves a brand by brandId


Request 
path Parameters
brandId
required
string
The ID of the brand


 
query Parameters
expand
Array of strings
Specifies additional metadata to be included in the response


Items Enum: "themes" "domains" "emailDomain"  
Responses 
200
Successfully retrieved the brand


403
Forbidden


404
Not Found


429
Too Many Requests


get/api/v1/brands/{brandId}
Request samples 
Response samples 
application/json
{}
Replace a Brand
OAuth 2.0: okta.brands.manage
Replaces a brand by brandId


Passing an invalid brandId returns a 404 Not Found status code with the error code E0000007.


Not providing agreeToCustomPrivacyPolicy with customPrivacyPolicyUrl returns a 400 Bad Request status code with the error code E0000001.


Request 
path Parameters
brandId
required
string
The ID of the brand


 
Request Body schema: application/json
required
name
required
string
The name of the Brand


 
agreeToCustomPrivacyPolicy
boolean
Consent for updating the custom privacy URL. Not required when resetting the URL.


 
customPrivacyPolicyUrl
string
Custom privacy policy URL


 
object (DefaultApp) 
 
appInstanceId
string
ID for the App instance


 
appLinkName
string
Name for the app instance


 
classicApplicationUri
string
Application URI for classic Orgs


 
emailDomainId
string
The ID of the email domain


 
locale
string (Language) 
The language specified as an IETF BCP 47 language tag


 
removePoweredByOkta
boolean
 Default:  false
Removes "Powered by Okta" from the sign-in page in redirect authentication deployments, and "© [current year] Okta, Inc." from the Okta End-User Dashboard


 
Responses 
200
Successfully replaced the brand


400
Bad Request


403
Forbidden


404
Not Found


429
Too Many Requests


put/api/v1/brands/{brandId}
Request samples 
application/json
{
  • "customPrivacyPolicyUrl": "https://www.someHost.com/privacy-policy",
  • "agreeToCustomPrivacyPolicy": true,
  • "removePoweredByOkta": true,
  • "name": "New Name For Brand",
  • "emailDomainId": "OeD114iNkrcN6aR680g4",
  • "locale": "en",
  • "defaultApp": {
    • "appInstanceId": "0oa114iNkrcN6aR680g4",
    • "appLinkName": null,
    • "classicApplicationUri": null
    }
}
Response samples 
application/json
{}
Delete a brand
OAuth 2.0: okta.brands.manage
Deletes a brand by brandId


Request 
path Parameters
brandId
required
string
The ID of the brand


 
Responses 
204
Successfully deleted the brand.


403
Forbidden


404
Not Found


409
Conflict


429
Too Many Requests


delete/api/v1/brands/{brandId}
Request samples 
Response samples 
application/json
{
  • "errorCode": "E0000006",
  • "errorSummary": "You do not have permission to perform the requested action",
  • "errorLink": "E0000006",
  • "errorId": "sampleNUSD_8fdkFd8fs8SDBK",
  • "errorCauses": [ ]
}
List all Domains associated with a Brand
OAuth 2.0: okta.brands.read
Lists all domains associated with a brand by brandId


Request 
path Parameters
brandId
required
string
The ID of the brand


 
Responses 
200
Successfully returned the list of domains for the brand


403
Forbidden


404
Not Found


429
Too Many Requests


get/api/v1/brands/{brandId}/domains
Request samples 
Response samples 
application/json
[
  • {
    • "brandId": "bndul904tTZ6kWVhP0g3",
    • "certificateSourceType": "MANUAL",
    • "dnsRecords": [
      ],
    • "domain": "login.example.com",
    • "id": "OcDz6iRyjkaCTXkdo0g3",
    • "publicCertificate": {
      },
    • "validationStatus": "VERIFIED",
    • "_links": {
      }
    }
]