Story Kit API

Story Kit includes a GraphQL API service that lets partners search Snapchat Stories by location, time, caption, media type, official username, and more.

Getting started

Create an ESDSA key pair

First you'll need to create and ESDSA key pair. To do this open up your terminal, and follow these two steps:

  1. Create the private key:

$ openssl ecparam -name prime256v1 -genkey -noout -out private-key.pem

  1. From your private key, create the public key:

$ openssl ec -in private-key.pem -pubout -out public-key.pem

Contact us with your public key

Send us a request using our contact form mentioning your public key. A Snap representative will assign an iss and a kid to you:

  • iss

    • A UUID string created to uniquely identify the partner's organization
    • Example: dcb57664-94ba-469e-ab4c-e2468ad218b9 is the iss we created for SnapAPITest
  • kid

    • The iss-version number
    • version number is to support key rotation in the future
    • Example: dcb57664-94ba-469e-ab4c-e2468ad218b9-v1 is the kid for SnapAPITest

Send a GraphQL request to Story Kit API endpoint

The Story Kit API only accepts HTTP POST requests that carry the query in the request body and the partner-signed JWT token in the X-Snap-Kit-S2S-Auth HTTP header. Learn how to successfully send an HTTP POST request in the steps below.

1. Construct a GraphQL query.

The Story Kit API is GraphQL based. For details, see the GraphQL defined in publicstoryapi.graphql.

To construct the query body, use any of the GraphQL client libraries you prefer.

2. Construct the X-Snap-Kit-S2S-Auth header.

The header is of the format Bearer <Unsigned Token>.<Signature>

The token is a JWT token. See the field descriptions below and learn how to generate the signature.

header = '{
 "alg":"ES256",
 "typ":"JWT",
 "kid": <string: <3pa organization id>-v<key version>>
}'

payload = '{
 "iss": <string: 3PA organization ID>,
 "aud": "PublicStoryKitAPI",
 "exp": <int32: expiry time in seconds from 1970-01-01T00:00:00Z>,
 "iat": <int32: issued time in seconds from 1970-01-01T00:00:00Z>,
 "hash": <string: sha256Hex of request body in lower case hex chars>
}'

Here's how to sign the token:

privateKey = <string: private key>
unsignedToken = base64.rawurlencode(header) + '.' + base64.rawurlencode(payload)
signature = base64.rawurlencode(ecdsaSigner.sign(privateKey, unsignedToken))
authorizationHeader = 'Bearer ' + unsignedToken + '.' + signature
request.header(X-Snap-Kit-S2S-Auth’, authorizationHeader)

And here is an example of the X-Snap-Kit-S2S-Auth header:

{
  "alg": "ES256",
  "kid": "dcb57664-94ba-469e-ab4c-e2468ad218b9-v1",
  "typ": "JWT"
}

Payload

{
  "aud": "PublicStoryKitAPI",
  "exp": 1529640526,
  "hash": "85f07ad28767eaab637a5f78ed3ebc23f58595d08db14df7d8f2df312106cab9",
  "iat": 1527630526,
  "iss": "dcb57664-94ba-469e-ab4c-e2468ad218b9"
}

Generated token

The generated token will look something like this:

Bearer eyJhbGciOiJFUzI1NiIsImtpZCI6ImRjYjU3NjY0LTk0YmEtNDY5ZS1hYjRjLWUyNDY4YWQyMThiOS12MSIsInR5cCI6IkpXVCJ9.eyJhdWQiOiJQdWJsaWNTdG9yeUtpdEFQSSIsImV4cCI6MTUyOTY0MDUyNiwiaGFzaCI6Ijg1ZjA3YWQyODc2N2VhYWI2MzdhNWY3OGVkM2ViYzIzZjU4NTk1ZDA4ZGIxNGRmN2Q4ZjJkZjMxMjEwNmNhYjkiLCJpYXQiOjE1Mjc2MzA1MjYsImlzcyI6ImRjYjU3NjY0LTk0YmEtNDY5ZS1hYjRjLWUyNDY4YWQyMThiOSJ9.OUKz6vPYH6VQVk0KK30qOaUWhvc50WH1HAa-VoXxHnkuG5JmZRFPizbDdEOjK8qSDNGPKuo_X--4MM7faBgLGw

JWT offers many token signing libraries in various languages. To simplify token signing, choose one that fits easily with your tech stack.

3. Send an HTTP POST request to the API endpoint

The final step is sending your HTTP POST request. Make sure it follows these conventions:

  • Carries the query in the request body
  • Includes the partner signed JWT token in the X-Snap-Kit-S2S-Auth HTTP header

Try it out with the beta test endpoint: https://kit.snap-dev.net/v1/stories/public

Example Code

Need an example? Check out our Node.js example on Github